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1. irfTRODUCTION 

The Workshop provides tools -for program devel opment . It provides 
-fac i 1 i t ies -for edi t ing, 1 anguage process! ng, and debuggi ng, as wel 1 as 
commands -for managing -files and con-figuring the system. The system 
a1 so i ncl udesmany otherutiljties. 

2. THE FILE MANAGER 

The File Manager al 1 ows you to manage and man ipul ate -f i 1 es and volumes. 

3. THE SYSTEM hVtf^WGER 

The System Manager allows you to set de-fault and con-figuration 
parameters -for the Lisa, and manage processes. 

4. THE EDITOR 

The Ed i tor all ows you to create and modi -fy text -f i les. These text -f i 1 es 
are used as i npu t to the Comp i 1 er and the Assembl er . 

5. THE PASCAL COMPILER 

The Compiler translates Pascal source code into object code. 
Transl at i on requ ires two steps; -first the comp i ler transl ates Pascal 
intol-codej then the code Generator translates the I-code into object 
code . 

6. THE ASSEMBLER 

The Assembler translates assembly 1 anguage programs i nto object code. 

7. THE LINKER 

The Linker combi nes object code -f i les i nto ex ecu tab 1 e programs. 

8. THE DEBUGGER 

The Debugger allows you to examine memory^ set breakpoints, and per-form 
other run-time debugging functions. 

9. USING EXEC FILES 

Exec -files allow you to execute a series o-f commands and programs 
automatically. 

10. THE UTILITIES 

Utility programs are provided -for debugging, con-figuring the system, 
and man i pul at i ng -f i les. 



•^ F> R EM Cj- I C E S 

A. ERROR MESSAGES 
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INTRODUCTION 

i.l The Workshop 1-1 

The Workshop provides the -functions necessary to develop and run programs 
on the Lisa. The Workshop can be booted from either a diskette or a Profile. 

1.2 Starting the Workshop 1-1 

The Workshop is started by booting the Lisa from a disk containing the 
Workshop software. You can use the Environments window to select one of 
several available environments. 

1.3 The Workshop User Interface 1-3 

The Workshop user interface consists of three command lines: the Workshop 
command line> the File Manager^ and the System Manager. 

1.4 File System Organization and Naming .............................. 1-4 

Files are stored on disk volumes and are accessed by specifying the volume 
name and the file name. 

1 .5 Using Utility Programs 1-7 

Utility programs provide additional functions for the Workshop. A utility 
program is started by choosing the RUN command from the Workshop 
command line. 

1.6 How do I Write and Run a Pascal Program? .......................... 1-8 

A Pascal program is written with the Editor. The source file must be 
compiled and linked before it can be run. 

1.7 Howdolwrite and Run an Assembly Language Program? ............ 1-8 

An assembly language program is written with the Editor. It must be 
assembled and linked with a Pascal main program before it can be run. 

1.8 How do I Use the BASIC Interpreter? 1-8 

A BASIC program can be written using either the Editor or the BASIC 
interpreter to create the source file. The BASIC interpreter will run the 
program. 

1.9 How do I write a COBOL Program? 1-8 

A COBOL program is written with the Editor. After writing the program^ 
enter, the COBOL language system to compile and run the program. The 
COBOL system is invoked by pressing C in response to the Workshop command 
prompt. 

1.19 The Operating System 1-8 

The Workshop runs under the Operating System for the Lisa computer. You 
can access operating system routines through the SYSCALL interface. More 
information about this interface can be found in the Operating System 
Reference Manual for the Lisa. 
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I rsj-TRODUC-r I orvi 

i.l The Workshop Manager. 

The Workshop allows you to develop and run programs on the Lisa. It provides 
tools necessary to write^ debug* and run programs in Pascal* BASIC* and 
COBOL. This manual explains how to use the Workshop and all of its tools. 

Access to all Workshop -functions is provided by command lines. The main 
command line* WORKSHOP allows you to edit programs* run utilities or user 
programs* and use the various languages available on the system- It also 
provides access to two subsystems; the File Manager* and the System 
Manager. 

The File Manager allows you to copy* delete* rename* and list disk files. It 
includes a backup -function* and functions for manipulating volumes. These 
functions are listed in the FILE- MGR command line* which is similar to the 
main command line. (See Chapter 2.) 

The System Manager provides for system configuration and defaults and 
process managment. Its commands are listed in the SYS-MGR command line. 
(See Chapter 3.) 

All command lines are displayed at the top of the Lisa screen. If there are 
more commands than will fit on one line* a "?" is at the end of the line. 
Pressing "?" will display the remaining commands. To access any command* 
press the first character of the command name. To redisplay the first 
command line* press RETURN. 

Most commands will ask for additional information. Type in the information 
using the Lisa keyboard. Some questions have a default value* displayed in 
square brackets ([default]). To accept the default value* press RETURN. If 
you don't want the default value* type in the value you want. 

The Lisa system can display one of two screens* called the main screen and 
the alternate screen. The Workshop system normally displays on the main 
screen. The alternate screen is used by the system debugger. You can 
change to the other screen display by pressing the right hand OPTION and 
ENTER keys. The System Manager contains the Console command* which can 
be used to specify where the Workshop should display. 

The Workshop can be used to write programs in Pascal* COBOL* and BASIC. 
To use these languages* refer to the appropriate language manuals. In 
addition to this manual* you will need: 

For Pascal Programming: 

• Pascal Reference Manual for the Lisa 

• MC68000 16 Bit Microprocessor User's Manual (for assembly language 
programming) 

• Operating System Reference Manual for the Lisa (for information on 
system calls) 
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For BASIC Programming: 

• BASIC User's Guide -for the Lisa 
For COBOL Programming: 

• COBOL User's Guide for the Lisa 

• COBOL Re-ference Manual for the Lisa 

If you have only a BASIC or COBOL system^ you will not have all the software 
described in this manual. The portions of this manual that will be most useful 
to BASIC and COBOL programmers are: 

9 The Introduction, which describes how to use the WorKshopi 

• The File Manager, which describes files and how to manipulate them. 

• The System Manager, which describes setting up the system 
configuration parameters. 

• The Editor, which describes how to create and modify text files that are 
used as source files. 

You may also use some of the utilities if they are included in your software, 

1.2 Starting the Workshop 

The Workshop can be booted from a diskette or a Profile. It will most 
commonly be used with a Profile. 

To start the system, boot from a disk that contains the Workshop software. 
If your disk contains only the Workshop environment, the Workshop command 
line will appear at the top of the screen. If you have more than one 
environment (for example, the Workshop and the desktop) you can use the 
Environments window to start up the environment you want, and switch 
between them. 

The Environments Window allows you to select the environment you want to 
start. You can also set a default environment that will be started 
automatically when you boot the system. To access the environments window 
while booting the system, press any key while the Lisa is starting up. The 
environments window will be displayed. 

The Environments window is shown in Figure i-i. It displays five buttons: 

Power Off Turn off the Lisa 
Restart Reboot or reset the Lisa 

Start Start the selected environment 

Set Default Set the default to the selected environment 
No Default The Environments window will always be displayed on 
startup. 

To select an environment, move the pointer to the checkbox of that 
environment and click the mouse button. Then move the pointer to the start 
button and click. The selected environment will start. - 

To access the Environments window from the Workshop, and select another 
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environment^ use the Quit command -from the Workshop command line? or 
press the on-o-f-f button. To access the Environments window from the 
Desktop* press the on-of-f button while holding down the (apple) key. 
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Figure i-1. The Environments Window 

1.3 The Workshop User Inter-face. 

When the workshop environment is selected* the system will come up with the 
Workshop command line at the top o-f the screen. This command line lists all 
the actions you can currently request o-f the system. The Workshop line 
displayed contains only some o-f the commands available. The rest of the 
commands can be displayed by pressing "?'S the last symbol on the line. The 
original command line can be redisplayed by pressing RETURN. A command is 
executed by pressing the first letter of the command name. 

There are two other subsystems that have separate command lines; the 
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File-Manager» and the System-Manager. Their command lines can be 

accessed from the Workshop command line> and are used the same way. 

You can terminate the operation o-f most commands by pressing (apple) 
period. You can turn o-f-f the Lisa by pressing the on-o-f-f button at any time. 
The system will shut down in an orderly manner. A diskette can be inserted at 
any time. It will automatically be mounted and accessible. Diskettes are 
ejected by pressing the diskette button. 

The main^ or Workshop* command line is as -follows: 

WORKSHOP: FILE-MGR, SYSTEM-MGR, Edit, Run, Pascal , Basic, Cobol , Quit, ? 

The additional portion^ displayed by pressing "?", is: 

Assemble, Debug, Link, MakeBackground, Generate 

All the main command line commands are described below. 

FILE-MGR (F) 

This command puts you into the File Manager subsystem, which is used to 
manipulate the files and volumes on the system. For more information on the 
file manager* see Chapter 2 in this manual. 

SYSTEH-MGR (S) 

This command puts you into the System Manager subsystem. This subsystem 
provides various configuration and utility functions. See Chapter 3 in this 
manual for more information. 

Edit (E) 

The Edit command puts you into the text editor, which is used to create and 
modify text files. The Editor is used to create source files for BASIC, 
COBOL, and Pascal. It is also used for assembly language programming and to 
create exec files. The Editor is described in Chapter 4 in this manual. 

Run (R) 

The Run command causes a compiled and linked program to execute. This 
command is used for user-written Pascal programs, utility programs, and any 
other software that runs under the Workshop. The Run command asks you for 
the file to run. This file must be an executable object file or an exec file. (An 
exec file name must be preceded by a "<" .) If you do not give it a complete 
pathname, the Run command will search through up to three default volumes 
for the file. These defaults can be set by the File-Manager's Prefix 
command. See the Prefix command in Chapter 2 for more information. 

The Run command will also accept an "exec file" as input. An exec file is a 
scenario of commands for the Workshop system to carry out. An exec file 
name must be preceded by a "<" to be processed correctly. For more 
information on exec files, see Chapter 9 in this manual. 

Pascal (P) 

This command starts the Pascal compiler. The compiler asks for the input 
file, which must be a text file; the listing file; and the output file, which will 
contain the object file. The Pascal compiler is described in Chapter 5. 
Further information on the Pascal language can be found in the Pascal 
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Reference Manual -for the Lisa. 

The compilation is done in two steps. The -first step* done by the Pascal 
command* produces an intermediate code file. After this^ you must use the 
Generate command* (press G) to generate an object file from the 
intermediate code file. 

Basic (B) 

This command puts you into the BASIC interpreter. More information on 

BASIC programming can be found in the BASIC User's Guide for the Lisa. 

Cobol (C) 

This command puts you into the COBOL language system. More information 
on COBOL programming can be found in the COBOL User's Guide for the Lisa 
and the COBOL Reference Manual for the Lisa . 

Quit <Q) 

The Quit command ends the Workshop environment. You can access the 

Environments window to start another environment. 

Assemble (A) 

The Assemble command starts the assembler. Further information on the 
assembler can be found in this manual in Chapter 6. Additional information on 
the assembly language can be found in the MC 68800 Microprocessor User's 
Manual . 

Debug (D) 

The Debug command causes your program to run with a breakpoint inserted at 

the first instruction in the program* so you can use the debugger on the 

program. More information on the Debugger can be found in Chapter 8 of this 

manual. 

Link (L) 

The Link command executes the Linker. The Linker is used to prepare 
compiled Pascal programs and assembled routines for execution* and to link 
together separately compiled pieces of a program. The Linker is described in 
Chapter 7. 

MakeBackground (M) 

The MakeBackground command allows you to start up a background process* 
then continue using the Workshop for other functions. It is assumed that the 
backgrond process will not try to display on the console. 

Generate (G) 

The Generate command converts intermediate code files produced by the 
Pascal compiler into object code. It is used with the Pascal compiler and is 
described in Chapter 5. 

1.4 File system organization and naming 

Files are stored on volumes* that are mounted on devices. A volume has a 
name and a directory of files that it contains. A file is specified by giving the 
name of the volume and the name of the file: 

-volumename-filename 
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The Workshop mainiiains a working directory; you can access -files in it 
without specifying a volume name. The working directory can be. changed by 
using the File Manager's Pre-fix command. Files on the working directory can 
be specified by just the file narne^ with no leading "-": 

filename 

Further information on the file system can be found in Chapter 2 of this 
manual and in the Operating System Reference Manual for the Lisa. 

1.5 Utility Programs. 

There are various utility programs provided with the Workshop. These are 
used for functions not as commonly used as the commands. 

The utilities are described in Chapter 10. 

You must Run utilities. Select the Run command from the main command line 
by pressing R when the main command line is displayed. The system will ask 
you for the name of the file to run. Type in the name of the utility you want to 
run. 

1.6 How do I Write and Run a Pascal Program? 

To write and run a Pascal program* proceed as follows: 

1. Use the Editor to create a text file with the Pascal source program. See 
Chapter 4 in this manual for more information on editing the file. See 
the Pascal Reference Manual for the Lisa for information on the 
language. 

2. Compile the program using the Pascal command (press P while the 
Workshop command line is displayed) from the main command line. The 
output from the compiler is an intermediate file. 

3. The output from the Pascal command is an I-code file. Use the Generate 
command to convert the I-code file into an object file. To use the 
Generator* press G when the Workshop command line is displayed. See 
Chapter 5 for more information on compiling Pascal programs. 

4. Link the program using the Link command. In order to be executable* 
the program must be linked with the Pascal support routines contained 
in lOSPASLIB. For other applications you may also use other libraries 
and units* or assembly language routines. More information on the 
Linker can be found in Chapter 7. 

5. The linker produces an executable object file. Press R to run the 
program. 

Information on making system calls from Pascal can be found in the Operating 
System Reference Manual for the Lisa. 

1.7 How do I Write and Run an Assembly Language Program? 

Assembly language programs must be called as procedures of functions from a 
Pascal main program. To write an assembly language routine^ proceed as 
follows: 

1. Use the Editor to create an assembly language source program. See 
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Chapter 6 o-f this manual -for information on assembly language. 
Chapter 4 describes the Editor. 

2. Press A to execute the Assembler. The Assembler accepts the text -file 
you created and produces an ob^ct -file. 

3. Declare the routines you wrote in assembly language as EXTERNAL in 
the main Pascal program that calls them. 

4. Use the Pascal and Generate commands to create an object -file -from the 
Pascal program. See Section 1.6 for more information. 

5. Use the Link command to link the Pascal object file> the assembly object 
file, lOSPASLIBt and any other needed units or libraries. 

6. Use the Run command to run the resulting object file, 

i.8 How do I use the BASIC Interpreter? 

To use the BASIC interpreter^ proceed as follows: 

1. Use the Basic command by pressing B when the main command line is 
displayed. You will enter the BASIC interpreter. 

2. Enter the BASIC language statements and commands necesary to write 
and execute your program. The BASIC interpreter can execute 
statements immediatly or save them to run later. You can return to the 
main command line by using the BASIC command BYE. 

You may also use the Editor to prepare or modify the BASIC source program, 
then use the BASIC interpreter to run it. See Chapter 4 in this manual for 
more information on the Editor. 

See the BASIC User's Guide for the Lisa for more information on the 
language. 

1.9 How do I Write a COBOL Program? 

To write a COBOL program > proceed as follows: 

i. Create a text file containing the source program by using the Editor, 
See Chapter 4 in this manual for more information on the editor. 

2. Press C to enter the COBOL language system. More information on 
COBOL programming can be found in the COBOL User's Guide for the 
Lisa and the COBOL Reference Manual for the Lisa . 

1.19 The Operating System. 

The Workshop runs under the Operating System of the Lisa computer. You 
can use some operating system routines from a Pascal program to perform 
special system functions for you. These system calls are defined in the 
intrinsic unit SYSCALL. More information on the syscall interface and 
routines can be found in the Lisa Operating System documentation. 
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THE FIUEMANAGER 

2.1 The File Manager 2-1 

The File Manager allows you to manipulate -files^ volumesf and devices. 

2.2 Using the File Manager 2-1 

Press F at the workshop command line to display the File Manager commands. 
The first letter of each File Manager command makes it work. 

2.3 The File Manager Commands 2-i 

This section lists and defines all File Manager operations. 

2.4 Disk Storage Organization and File Naming 2-6 

Each disk can contain a volume which has a directory of files. File extensions 
(.TEXTt .OBJ, etc.) are added to some files with special uses. 

2.5 Using Wild Card Characters 2-7 

Wild card characters allow you to name groups of files by giving filename 
patterns to be be matched. The wild card characters are =>$*?. 

2.6 How do I Copy a File? 2-8 

To copy a file, use the File Manager Copy command. If you want the old file 
deleted after the copy is successful, use the Transfer command. You can 
copy multiple files by using wild cards. 

2.7 HowdolDelete a File? 2-9 

To delete a file, use the File Manager Delete command. You can delete more 
than one file by using wild cards. 

2.8 How do I Create and Use a Volume? ................................. 2-9 

Use the Initialize command to create a volume. The volume must be mounted 
before you can use it. 

2.9 How do I Change the Name of a File or Volume? 2-10 

To change the name of a file or volume, use the Rename command. 

2.ie How do I list Existing Files? ..................................... 2-ie 

To list all the files on a volume, use the List command or the Names command. 
You can use wild cards to list subsets of the files on the volume. 
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2.1 The File Manager 

The File Manager is a subsystem o-f the Workshop that provides -file and 
device manipulation facilities. It handles mosi: of the tasks of transferring 
information from one place to another. Using the file manager^ you can do 
such things as make copies of filesf list directories^ rename or delete files* 
find out what volumes are on line, initialise new disks or diskettes, print 
files, and soon. See the Operating System Reference Manual for the Lisa for 
more information on the file system and supported devices. 

A file specifier can be an OS pathname (representing a file on a disk or 
diskette), an OS volume name (for example, -MYDISK), the name of a physical 
device (for example -RS232A), or the name of a logical device (for exampel 
-PRINTER). File specifiers may contain wildcards (see section 2.5) allowing 
them to specify a collection of files. 

2.2 Using the File Manager 

To use the File Manager, press F in response to the Workshop command 
prompt. The File Manager begins executing, and displays the File Manager 
prompt line. 

The File Manager prompt line is: 

FILE-MGR: Backup, Copy, Delete, List, Prefix, Rename, Transfer, Quit, ? 

To display the additional commands, press "?". The line of additional 
commands is: 

Equal, FileAtiributes, Initialize, Mount, Names, Online, Scavenge, Unmount 

To redisplay the original command line, press RETURN. 

To execute any command, press the first character of that command when the 
File Manager command line is displayed. Most commands will ask for file 
names, or other input parameters. If there is a default value for a parameter, 
it is displayed in square brackets ([default!). To accept the default, just 
press RETURN. If you do not want the default, type in the response you want. 

2.3 The File Manager Commands 

The File Manager commands are listed in the File Manager prompt line. They 
are: Backup, Copy, Delete, List, Prefix, Rename, Transfer, Quit, Equal, 
File Attributes, Initialize, Mount, Nam.es, Online, Scavenge, and Unmount. 

Some of these operations can be performed either on a single file, or on a list 
of files specified by wild card characters. 

Each of these operations is described below. Information on wild card 
characters can be found in section 2.5 below. 

2.3.1 Backup (B) 
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This command executes a simple backup utility t similar to Copy. It asks for 
source and destination file specifierSf which will most likely contain wild 
cards* (see Section 2,5) and compares the source -files to the destination 
•files. Whenever the contents of the two files are not equalt the file is copied. 
If a source file is missing from the destination* it is copied. 

2.3.2 Copy (C) 

The Copy command copies files. It asks for a source file specifier and a 
destination file specifier. You may use wild cards if you want to copy more 
than one file. The source file(s) are not changed by this command. 

The de-fault is not to verify copy operations. You can change this default 
with the Validate command in the System Manager. If you change the default, 
the source file will be compared to the destination file after the copy 
operation to insure that they are the same. The Validate command is 
described in Chapter 3. 

You can copy files to the -PRINTER or the -CONSOLE logical devices. Text 
files (ending in ".text") will be displayed as a text file. All other files will be 
sent byte by byte . 

2.3.3 Delete (D) 

The Delete command is used to delete a file or a number of files specified by a 
wild card expression. It asks you to specify the files to be deleted. 

2.3.4 List (L) 

The List command lists information about the files matching the given file 

specification. If all you need is the names of the files* use the Names 

command described below. 

t If the file specifier is a file name (for example -MYDISK-example.text) 
that file is listed. 

• If the files specifier is a volume name (for example -MYDISK), 
information about all files on the volume is listed. 

• If the file specifier includes a wildcard character (for example, 
-MYDISK-=.text) information about all matching files is listed. 

The list command displays the following information: 

Filename The name of the file. 

Size The logical file length in bytes. 

Psize The physical length of the file in blocks. 

Last-Mod-Date Date and time the file was last changed. 

Creation-Date Date and time the file was created. 

Attr File attributes, a combination of the following: 

C File was closed by the OS 

L File is locked (cannot be deleted) 

File was left open when the system crashed 

P File is Protected 

S File has been Scavenged. 
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An example o-f the lisl: display is shown in figure 2-1. 



Contents o-F ^oluwe -PARAPORT-= 



Filename 


Size 
13824 


Psize 
27 


Last-Mod-Date 


Creation-Date 
81/84/83-18:59 


Attr 


ALERT 


81/31/83-11:17 




arii^2 


1924 


2 


81/19/83-19:56 


91/12/83-14:55 




ASSEMBLER. OBJ 


51712 


181 


82/84/83-16:43 


92/84/83-15:43 




BVTEDIFF.OBJ 


2568 


5 


82/84/83-16:43 


82/82/83-17:18 




CHANGESEG.OBJ 


2948 


4 


92/84/83-16:43 


32/82/83-16:52 




cUslib.obj 


1536 


3 


81/25/83-15:15 


81/25/83-15:15 




CODE. OB J 


68528 


119 


82/84/83-16:44 


82/84/83-15:24 




CODESIZE.OBJ 


8784 


17 


82/84/83-16:44 


92/82/83-16:57 




D.LIST 


292 


1 


81/88/83-92:86 


81/88/83-92:86 




dbiib.obj 


76288 


149 


81/31/83-11:17 


81/85/83-15:84 


CO 



Figure 2-1. The Lisi Display 

2.3.5 Prefix (P) 

This command allows you to set up default volume names to search when you 
specify a file name without a volume name. You can set a sequence of up to 
three volume names that will be searched in order when you try to run a 
program until the file is found. The first prefix is the name of the working 
directory. li will be searched anytime you specify a filename without a 
volume name. Boot defaults for prefixes can be set using this command. The 
second and third prefixes will be searched when you try to Run a program 
without specifying the volume it is on. 

This command asks you for the three prefixes. If you want to accept the 
default^ (if any)> press RETURN. If you want to set a prefix t type in the 
volume name. If you want to have no prefix > press CLEAR as the prefix for 
that level. 

2.3.6 Rename (R) 

The Rename command allows you to change the name of a file. It asks for the 
filename to change and the name to change it to. You can also use the Rename 
command to change the name of a volume. The Rename command can change 
the name of a number of files by using wild cards. See Sections 2.5 and 2.9 for 
more information. 

2.3.7 Transfer (T) 

The Transfer command asks for an input file specification and a destination 
file specification. It copies the input file(s) to the destination and then^ if 
the copy was successful^ deletes the input file(s). If you Transfer to the 
-console or the -printer t the input file will not be deleted. 

2.3.8 Quit (Q) 
This command 
command line. 



exits from the File Manager subsystem to the Workshop 



2.3.9 Equal (E) 

The Equal command compares the contents of two files to determine whether 
they are exactly the same. It asks for the names of the files to compare^ then 
compares them byte by byte and tells you if they are equal or unequal. 

2.3.10 FileAttributes <F) 
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This command is used "to sei -file a-ti:ribu*tes. You can set the sa-fety at'tribute, 
which makes the -file so you cannoi: accidentally delete it. In order to delete a 
•file with the sas-fety attribute set, use the File Attributes command to unset 
the attribute on the -File. You can also make a -file into a protected master. 

Use the FileAttributes command by pressing F in response to the File 
Manager command prompt. It displays a command line: 

FileAttributes: ClearAttributeSf Sa-fety^ Protect, Quit. 

These commands are accessed by pressing the -first character of the 
command. They per-form the following -functions: 

Clear Attributes (G) 

The clear attributes command clears the Ct Of and S attributes on the 
specified volume. These attrubutes are set by the system* and have the 
•following meanings: 

C File was closed by the Operating System 

File was le-ft open when the system crashed. 

S File has been scavenged. 

The clear attributes command should be used be-fore scavenging a volume so 
that you can tell i-f any •files were changed. See the Scavenge command in 
Section 2.3.15 below -for more information. 

Safety (S) 

The Safety command allows you to set or remove the safety attribute on any 
file. When the safety attribute isset> the file cannot be deleted. To delete a 
file with safety on» use this command to remove the attribute > then delete 
the file. 

Protect <P) 

The Protect command is used to make a file into a protected master. This is a 
form of copy protection for object files. Once a file is made into a protected 
master* this protection cannot be removed. A protected master has the 
following characteristics: 

• It can be run on any Lisa machine 

• It can be copied on any one Lisa machine. 

• Copies made will run only on the machine that made the copies. 

• After the file is copied the first time* further copies of the master 
can be made only on the same machine. 
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NOTE 

Once a -file is made into a protected master, there is no way to 
unprotect it. Be sure you understand the characteristics of a 
protected master be-fore you create one. 

This protection scheme is -for executable object -files. Note that 
protecting a tile does not prevent you -from deleting it. 



Quit (Q) 

The quit command exits you from the file attributes subsystem to the File 
Manager. 

2.3.11 Initialize Q) 

The Initialize command is used to set up an OS device. It is used to format 
and initialize the file system on a diskette or ProFile. It asks you for the 
device name to initialize > the number of blocks to initialize, the volume name, 
and password. If you want the entire device to be initialized^ enter RETURN 
(accepting the de-fault) for the number of blocks. If the device is a diskette, 
it is formatted (ProFiles are factory formatted). Boot tracks are 
automatically written to any device that is initialized. An initialized device 
is automatically mounted. 

The initialize command will warn you if you attempt to initialize a disk that 
already contains a volume. A volume is initialized to allow a certain maximum 
number of files. You can make this number larger or smaller (if you know you 
will have a large number of small -files, for example) when initializing it. 

2.3.12 Mount (M) 

This command is used to make an OS device accessible. It requests a device 
name. It should be used whenever you connect anew device, such as a Profile. 
The Unmount command, described below, is used to remove a device. All 
configured devices are mounted at boot time. The configuration can be 
changed with the Preferences tool, which is described in Section 3.3 

2.3.13 Names (N) 

The names commandis a faster version of the List command. It gives you a list 
of file names only. It asks for a file specifier, and displays the names of all 
files matching the given file specifier. 

2.3.14 Online (0) 

The Online command produces a list of all the devices that are currently 
mounted and available. It tells you the devices mounted, the names of the 
volumes contained on them, the number of files on each volume, the size of 
the volume, and the amount of free space on it. The online display gives the 
following information: 

VolumeName The name of the volume. 

VolSize The number of blocks on the volume. 

OpenCount The number of files open. 

FreeCount The number of blocks still available. 
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FileCount The number o-f files stored on the volume. 

VolAt The attributes o-f the volume: 

B the boot volume. 

P the prefix volume. 

M volume is currently mounted. 



The Online display is shown in Figure 2-2. 
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Figure 2-2. The Online Display 

2.3.15 Scavenge (S) 

This command runs the OS Scavenger which restores damaged files. Files can 
be damaged any time the system terminates abnormally. The Scavenger 
searches through a disk and restores its directories* files* and allocation 
tables to a consistent state. 

A disk must be unmounted before it can be scavenged. Use the unmount 
command to unmount the disk, scavenge it* then mount it again to continue 
using it. The boot volume cannot be unmounted; therefore it cannot be 
scavenged- If the ProFile is normally your boot volume and you need to 
scavenge it* it is necessary to boot from a diskette and run the Scavenger 
from it. 

If a file is changed in any way by the Scavenger, the file attributes will be set 
to S* for scavenged. This attribute is displayed by the List command. The 
changes made to the file may or may not affect the data in the file, depending 
on what state the file was in when it was scavenged. Check any file with the 
Scavenged attribute before relying on its contents. After the file has been 
checked, the Scavenged attribute can be removed with the FileAttributes 
command. 
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NOTE 

The -file sysi:em can get into an inconsistent state because the 
directories and allocation tables are Kept in memory and only written 
out to disk periodically. If there is an abnormal termination* such as a 
power failure f the changes to the state of the file system since these 
tables were written to disk will be lost. Information can also be lost if 
you disconnect a Profile from the Lisa without first unmounting it. If 
the disk is used after such an event, more data can be lost if the 
system allocates the same blocks to more than one file. 

The Scavenger will always return the disk to a consistent state, but it 
is possible to lose data when the system crashed. This damage can 
become even worse if the disk is used while in an inconsistent state. 

All Scavenged files should be checked before you depend on their 
contents. 



2.3.16 Unmount (U) 

This command makes a device inaccessible. It asks for a device name. Always 
unmount a device before disconnecting it. 

2.4 Disk Storage Organization and Naming 

Each disk contains a volume. The volume name is the name of the disk. 
Volumes are created with the Initialize command, which sets up the disk and 
puts an empty directory on it. As files are entered on the disk, their names 
are entered in the directory. A complete path name consists of a volume name 
followed by the file name in the following format: 

-volname-filename 

A working directory is maintained by the Workshop allowing you to access 
files on it without using the volume name. This working directory defaults to 
the boot device. The working directory can be changed by the Prefix 
command. The working directory is the first prefix specified in the Prefix 
command. Files on the working directory are specified by ^st the file name, 
with no leading "-": 

filename 

A volume must be mounted before it can be accessed. Volumes are mounted 
with the Mount command in the File Manager. To mount a volume, you specify 
the device on which it resides. Device names that can be used for disks are as 
follows: 

-UPPER The upper diskette. Drive i. 

-LOWER The lower diskette. Drive 2. 

-PARAPORT ProFile attached to the parallel port. 

-SLOT2CHAN2 ProFile attached to the M-port card in slot 2, channel 2, 
etc. 

There are also two serial devices, -RS232A and -RS232B . These provide 
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access to e>{ternai RS232 devices. 

There are three logical devices that can be used -for input and output. These 
devices are: 

-CONSOLE Used -for output to the screen and input -from the 

keyboard. The actual device which is used as the 
console can be changed by the Console command in the 
System Manager. See Section 3.2. 

-PRINTER Used to output to the printer. The physical port that 

the. printer is connected to is set by the Pre-Perences 
tool > described in Section 3.3.3. 

-KEYBOARD Used as a non-echoing input device from the keyboard. 

This is the keyboard on the console device. 

Certain types o-f files in the system have standard file extensions. These 
extensions make it easier to keep track of the different types of files. These 
file extesions are: 

.TEXT This indicates a text file in the format created by the Editor. 

.OBJ This indicates an object code file. Object files are created 
by the code generater^ the Assembler, and the Linker. Ob>ct 
files created by the Linker are executable. 

.1 This indicates an intermediate (I-CODE)file produced by the 

Pascal compiler. The Generate command will convert an 
intermediate file into an object code file. 

.LIB This indicates a .library file. 

.SHELL This indicates a shell file that can be started by the 
environments window. 

2.5 Using Wild Card Characters 

Wild card characters allow you to specify a set of files to operate on. The 
command is performed on ail files whose pathname matches the set specified. 
Wild card characters are "=", "?'S and "$". These characters are used as 
follows: 

string l=5tring2 

The "=" character stands for any sequence of characters that can be ignored. 
The surrounding strings (stringi and string2) must be matched exactly, 
ignoring case. Either or both strings can be null. Here are some examples of 
using the "=" wild card character as a source file name: 



ds=.text 
=.obj 



all files beginning with ds and ending in .text, 
all files ending with .obj. 
all files. 



When "=" is used in a destination file name, it is replaced with the characters 
that were matched by a wild card in the source file. -This allows you to do 
operations like change the name of a list of files as they are copied. Here are 
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examples o-f using "=" as a desirination file name: 

dss.tex-t "to bu/ds=."tex-t Change all files starling wiihdsand 

ending with .text so they are pre-fixed 
with bu/ 

=.obj to x/=.obj Put >t/ in -front of the -file name. 

string l?5tring2 

The "?" character is the same as the "="t except that the system asks you to 
confirm each file name before performing the operation. The "?" wild card 
can be used only as a source string. 

When you use a "?" in a sourcp specifier, you are presented with a list of files 
that match it. You can move backwards and forwards through the list by 
using the up and down arrows on the numeric keypad. Press "Y" beside every 
-file that you want to be processed. When you have selected all the files you 
want, press RETURN. The operation will then be performed on the files you 
selected. 

string l$string2 

The "$" character is used only as a destination filename. It is replaced by the 
entire source ffle name. For example, if you have the source files matching 
ds=*text: 

dsfmgr.text 
dssmgr.text 

If the destination expression isbk$, the output files will be*. 

bkdsf mgr.text 
bkdssmgr.text 

Contrast this with the output expression bk=, which results in: 

bkfmgr.tex t 
bksmgr.text 

2.6 How do I Copy a File? 

You can either Copy a file and leave the original file intact, or you can 
Transfer the file, which will copy the file, then delete the original file. To 
copy a file, proceed as follows: 

i. If you are not in the File Manager subsystem, enter it by typing F in 
response to the Workshop command prompt. 

2. Press C to start the Copy command. (Press T, for transfer, if you want 
the original file to be deleted after the copy operation.) 

3. Enter the pathname of the file you wani copied. Press RETURN. 

4. Enter the pathname you want the file to be copied to. Press RETURN. 
The file will be copied or transferred as you specified. 

If you want to copy a number of files with similar names, or all the files on a 
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volume > you can use wild card characters. See section 2.5 -for more 
information on using wild cards. Wild cards can also be used to rename all the 
copies o-f the selected -files. 

You can use a shorthand method o-f entering the -file names by entering both 
the source and destination -file names* separated by a comma (») in response to 
the request -for the source -File. 

See Figure 2-3 -for examples o-f copy and trans-fer operations. 

Copy -from what exi st i ng -f i le<s)? myprog 
Copy to what new -file? -backup-f 

(This copies the -file myprog on the working directory to the volume 
-backup with the same name* myprog.) 

Copy -from what exi st ing -f i 1 e<s)? ds= 
Copy to what new -file? -backup-^ 

(This copies all files beginning with ds on the working directory to the 
volume backup with the same file name.) 

Transfer from what ex i st i ng f i 1 e<s)? -osback-osQ= 
Transfer to what new file? -oswork-f 

(This copies all files beginning with osg on the volume -osback to the 
volume -oswork using the same file name. When the files have been 
copied successfully* the original files are deleted.) 

Transfer from what ex i st i ng f i le<s>? -osback-osQ= ,-oswork-'$ 
(This is the shorthand version of the above transfer operation.) 

Copy from what existing file(s)? ds=j-backup-backds= 

(This copies all files beginning with ds in the working directory to the 
volume -backup with back inserted as the beginning of each file name.) 

Figure 2-3. Copy and Transfer operations 

2.7 How do I Delete a File? 

To delete a file* proceed as follows: 

1. If you are not in the File Manager subsystem* enter it by typing F in 
response to the Workshop command prompt. 

2. Select the Delete command by pressing D. 

3. Enter the pathname of the file you want to delete. 

4. The system asks you to confirm that you want to delete the file. Reply 
Y to delete the file or N to keep it. 

If you want to delete more than one file* you can use wild cards. See the 
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section "Using Wild Card Characters" in this chapter for more in-formation- 

2.8 How do I Create and Use a Volume? 

A volume can be created on either a diskette or a ProFile disk. Each disk can 
contain one volume. Creating a volume on a disk gives it a name and sets up a 
directory for files. 

1. If you are not in the File Manager subsystem* enter it by typing F in 
response to the Workshop command prompt. 

2. Press I to invoke the Initialize command. This command asks for- 

• The device name (upper or lower for a diskette > slot2chan2 for aProFile* 
etc.) 

• The number of pages to initialize. The default is to initialize the whole 
device. 

• The volume name. 

• The volume password (optional). 

t The maximum number of files on the device. The default is a good value 
unless you are using a large number of very small files or a few very large 
files. 

The volume is initialized # with an empty directory. (If the device is a diskette 
it is first formatted.) The system will warn you if you are initializing a 
device that has an existing volume on it> and give you a chance to change your 
mind before destroying the existing volume. 

After initializationt the device is automatically mounted so it can be used. 

2.9 How do I Change th^ Name of a File or Volume? 

The Rename command allows you to change the name of any file. 

1. If you are not in the File Manager subsystem? enter it by typing F in 
response to the Workshop command prompt. 

2. Execute the Rename command by pressing R. 

3. Enter the pathname of the file or volume you want to rename. 

4. Enter the new name. 

The name of the file or volume is changed. 

You can use the Rename command to change the name of a group of files by 
using wild card expressions. 

2.18 How do I List Existing Files? 

You can use either the List command, or the Names command to list existing 
files. The Names command executes much faster than the List command* but 
it gives you only the file names. 

1. If you are not in the File Manager subsystem, enter it by typing F in 
response to the Workshop command prompt. 



o 



Execute the List command by pressing L* or the Names command by 
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pressing N. 

3. H you want to list an entire volumet enter the pathname o-f the volume or 
device. I-f you want to list only a certain set of filest enter a wild card 
expression or pathname describing the files to be listed. 

The listing produced by the list command is explained in Section 2.3,4. 

For more information on wild card characters* see Section 2.5 in this 
chapter. 
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Cha.p±er 3 
THE SYSTEM MANAGER 

3.1 The System Manager 3-2 

The System Manager allows you to set certain system de-faults and set up the 
Lisa con-figuration J including eKtemal device connections and the startup 
device. 

3.2 The System Manager Functions 3-2 

The System Manager is activated by pressing S in response to the Workshop 
command line. It allows you to set system de-faults and access the 
Pre-ferencBS tool that allows you to set the configuration of the system. 

3.3 The Preferences Tool 3-3 

The Preferences tool allows you to set up system details and to specify what 
external devices are connected. 

3.4 Process Management ................................ 3-6 

The process management subsystem allows you tomake selected processes 
resident, display the status of all currentl y ex ist ing processes, and 
remoMe processes. 
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3.1 The System Manager. 

The Syslem Manager allows you to set system de-faults and con-figuration. It 
allows you to: 

• Set the Lisa system characteristics such as screen contrasts speaker 
volume^ and time lags for repeating keys. 

• Set the configuration of external devices such as disks and printers. 

• Set the default start up device. 

• Set processes to be resident or non resident, to allow you to performance 
tune your Workshop system. 

• Set what device is to be the console. 

• Redirect output from the console to a file or external device. 

• Monitor all currently existing processes* and remove processes. 

3.2 The System Manager Functions. 

By pressing S in the main comand line> you can enter the System Manager 
subsystem. The System Manager command line works the same as the main 
Workshop command line. Pressing "?" shows you the additional line of 
commands. 

The System Manager command line is: 

SYSTEM-MGR: ManageProcess, OutputRedirect* Preferencesr Time^ Quit* ? 

Press "?" to see the additional commands: 

Consoiet FilesPrivate» Validate 

Each System Manager command is described below. 

ManageProcBss (M) 

This command puts you into a process management subsystem* which allows 
you to select which processes should be resident for performance reasons. It 
also allows you to display the status of all currently existing processes* and 
remove processes. This subsystem is described in section 3.4 below. 

OutputRedirect (0) 

The OutputRedirect command allows you to send a copy of all output that is 
displayed on the console to another device (such as the -printer) or to a file 
on a disk. The command asks you for the pathname to send the copy to. In 
order to return to displaying only on the console, use the command again and 
redirect the output to the -console device (the default). 

Preferences (P) 

The Preferences tool is used to set up the configuration of the Lisa system 

and the Workshop. It is described in section 3.3 below. 

Time (T) 
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The Time command allows you io sei the date and time. The date and time will 
be maintained automatically by the Lisa system. 

Quit (Q) 

The Quit command exits -from the System Manager back to the main Workshop 

command line. 

Console (O 

This command allows you to change where the Workshop console is displayed. 
It may be displayed on the main screen (the default) or on the alternate 
screen (where LisaBug displays), or on an external terminal connected to the 
RS232A or B port. 

FilesPrivate (F) 

The FilesPrivate command selects whether or not the private system files 
should be displayed by the List command. The default is to not display the 
private files. Private files are any files with a name beginning with "{". 
These file names are used by the system for files you should not normally need 
access to. 

Validate (V) 

The validate command is used Io set up defaults for verifying operations. 
Currently the only default of this type tells if the system will verify file 
copies or not. The system verifies a copy by comparing the original file with 
the copy to be sure they are the same. The boot default is to never verify. 
You should have no reason to verify unless you something is wrong with your 
disk. 

3.3 The Preferences Tool 

The Preferences tool is started by pressing P in response to the System 
Manager command line. After you are finished with it* you can exit back to 
the System Manager by selecting Quit from the Tools menu. 

The Preferences tool allows you to set up your Workshop system the way you 
want it. It contains four sections: 

• Convenience settings that allow you to set up the screen contrast, the 
speaker volume > and repeat delays. 

• Device connections that tell the Lisa system what external devices are 
connected. 

• Startup that tells the Lisa what device to use as a startup device. 

• Workshop defaults that set up things the Workshop needs to know. 

These default settings are stored in parameter memory, a small area of 
memory that is preserved as long as the Lisa is plugged into a working outlet 
and for up to 16 hours when the Lisa is unplugged. If your Lisa is without 
power for longer than thist the preference settings will be restored from 
information on the startup disk. 

Any changes made with the Preferences tool change. Parameter Memory 
immediately, but some of them> such as device connections and startup 
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op-tions have no e-ffect until the system is booted again. 

The preferences tool displays a window containing a number of buttons and 
checkboxes. You set the values you want by using the mouse to move the 
pointer to the desired options and clicking. 

These four areas are described briefly below. More information on the first 
three areas can be found in the Lisa Owners Guide Section D. Select the 
area you want to view or change by moving the pointer with the mouse to the 
checkbox in front of the section name and clicking. 

3.3.1 Convenience Settings. 

The Convenience Settings portion of the Preferences tool allows you to 
customize the input and output characteristics of the Lisa. These 
characteristics are divided into three sections: Screen Contrast, Speaker 
Volume, and Rates. The Convenience Settings display is shown in Figure 3-i. 
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Figure 3-i. Convenience Settings. 

Screen Contrast 

The contrast portion contains three sections. The -first allows you to select 
the normal screen contrast level. Check in a contrast box until the contrast 
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level is comfortable. Checking a box immediately changes the contrast. 

The Lisa screen automatically dims if no activity is taking place on the 
screen to protect the screen from damage. The delay time before this 
dimming takes place is set with the Fade Delay section. 

The third section allows you to set the dim contrast level. Checking a box in 
the Dim Level section makes the screen dim to that level until you move the 
mouse. 

Speaker Volume 

The speaker volume section allows you to set how loud the Lisa's audible 

alerts will be. Checking a box causes two beeps at the level you selected. 

Rates 

There are three rates that can be set* two for the keyboard and one for the 
mouse. The first is the initial keyboard repeat delay. This is the length o-f 
time a key must be depressed before it begins repeating. The second is the 
subsequent repeat delay. This is how quickly a key repeats after it has 
started repeating. The third rate is the mouse double click delay. This sets 
the maximum amount of time between two clicks that will be considered a 
double click. These three values should be set for your most comfortable use. 

3.3.2 Start Up. 

The Start Up display allows you to specify the boot device » and the type of 
memory test to be performed on startup. The Start Up display is shown in 
Figure 3-2. 



Tools 






Preferences 
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Start Up From: 
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Mennory Test 

■ Brief 
D Thorough 

Figure 3-2. The Start Up Display. 

The Start Up display lets you select the Lisa system boot device. You are 
given a list of all possible boot devices. Select the one you want. 

The Start Up display also allows you to select a long or short memory test. 
The brief test takes about 36 secondst the long test takes about a minute. 

Changes made to the Start Up display are put into Parameter Memory 
immediately^ but have no effect until the system is booted again. 



3.3.3 Device Connections. 

The Device Connections 
connected to the Lisa. 



display allows you to specify what devices are 
When it is selected* it displays all ports that 
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currently exists along with the devices that are currently connected. To addt 
delete^ or change the device connected to a port^ select the port. All devices 
that may be connected to that port are displayed; you may also choose to have 
no device connected. When you select the device to connect^ any additional 
con-figuration options -for that type oi device are displayed. 

Any changes made to the device connections are made immediately to 
Parameter Memory? but they do not take e-f-fect until the next time the Lisa is 
booted. Atypical device connections display is shown in Figure 3-3. 
Tools 
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ill 
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Figure 3-3. A Device Connections Display. 
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3.3.4 Workshop 
The Workshop 
The Workshop 

Tools 



display allows you to set parameters 
display is shown in Figure 3-4. 



oi the Workshop system. 



□ 



Preferences 
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"1 
I Memory to use(assuming 1 megabyte machine} 
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Dhalf megabyte 



Enable Mouse Scaling? 

ino Dyes 



Figure 3-4. The Workshop Display. 

3.3.5 The Tools Menu 

The tools menu provides you with functions to access Parameter Memory. 
There are three -functions provided: Set PM to defaults; Quit; and Print PM. 
Set PM to de-faults sets parameter memory to the standard Lisa de-faults. 
Quit exits you -from the Pre-ferences tooif and puts a copy o-f the current 
settings o-f parameter memory on the disk. Print PM displays all the values in 
parameter memory on the console. 
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3.4 Process Management 

The Process Management subsystem Is started by pressingH in response 
to the System Manager command line. This subsystem displays the 
•fol lowing command 1 ine : 

ManageProcess: AddResident> DeleteResident, KillProcessi ProcessStatust Quit ? 

This subsystem is used to control which processes wi 11 be resident. 
Mak i ng a process resident means that after i t has run to compl et i on , i t 
will be suspended and retained in memory rather than terminated and 
removed -from memory . Th i s al lows it to restart -faster , because it does 
not have to be reloaded from disk . For example , if you are of ten using 
the Pascal compiler and the Editor, you can Improue the performance of 
your Workshop system for these ap pi icat i ons by mak ing the comp i 1 er and 
the Ed i tor res i dent . Th i s wi 1 1 al 1 ow much more rap i d sh i f t i ng between 
the two. 

See the Operating System Re-ference Manual for the Lisa for more 
inf^ormat ion on processes 

AddResident (A) 

The AddResi dent command adds a process to the 1 i st of^ processes that are 
resident. You supply the file name of^ the object file that you want to 
be made resident the next time it is executed. 

DeleteResident <D) 

The DeleteResident removes a process from the list of resident 
processes. 

Ki 11 Process <K) 

Th i s command termi nates a current 1 y ex i st ing process. 

ProcessStatus (P) 

The ProcessStatus command gives you information about all currently 
ex i st i ng processes. 1 1 provides the fol lowi ng inf ormat i on : 

Pathname The name of the object fi le in the process. 
ProcessID The unique identifier assigned to the process. 
State The current state of the process: Active, 

Suspended, or Wai t ing. 
Resident Tel 1 s you if th is is a resident process. 

Qu i t 

Exit from the processmanagement subsystem back to the System Manager 
command 1 i ne . 
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Cha.p-ter4 
THE EDITOR 

4.1 The Editor 4-2 

The Editor is used to create and modify text files. 

4.2 Using the Editor 4-2 

Start editing by pressing E in response to "the command prompt. The Editor 
will create a new file or edit an existing one. Operations are provided in five 
menus: File> Edit* Search ^ Type Style > and Print. The mouse is used to select 
menu items. 

4.3 Selecting Text 4-4 

The mouse is used to select text and to move the insertion point. 

4.4 Scrolling and Moving the Display ................................... 4-5 

The display can be scrolled by using the scroll bar on the right side of the 
window. The window can be moved by clicking in the title bar. The size of the 
window can be changed by using the size control box. 

4.5 The File Functions 4-5 

The File functions are used for retrieving and saving text files. You can also 
save or revert to a previous version and exit the Editor. 

4.6 The Edit Functions ................................................ 4-6 

The three basic Edit functions are cut r paste t and copy. The Edit menu also 
gives you functions to ad^st left and rights and to set tabs. 

4.7 The Search Functions 4-8 

Search gives you functions to find text strings in the file> and optionally 
replace them. 

4.8 The Type Style Functions 4-9 

The Type Style menu allows you to change the font that the file is displayed 
and printed in. 

4.9 The Print Functions 4-16 

The Print menu allows you to print the file^ and to specify the format it 
should be printed in. 
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The Editor 



Hi 



D I TOR 



4.1 The Ediior 

The Ediior is used to create and modi-fy text -files. These files may be used 
for many purposes including input to the language processors and as exec 
files. 

If the file you are editing is too big to fit on the screen, a portion of the file is 
displayed. This "window" into the file can be moved to display any part of the 
file you want. An example of the Editor display window is shown in Fiqure 
4-1. 

The basic editing operations are inserting characters, cutting a portion of 
the text, and pasting text into a new location. Items that are cut go into a 
special window called The Clipboard. Text on the Clipboard can be pasted 
into any place in the file, or into another file. 

All editing action takes place at the insertion point. The insertion point is 
marked by a blinking vertical line where the next character will be placed. 
Any characters typed, or pasted from the Clipboard will be inserted at this 
point. This is true even if the insertion point is not currently displayed in the 
window. The window will automatically be scrolled to show the insertion 
point. 

NOTE 

The editor is memory based. This means that there is a practical limit 
on the size of the file that can be edited. If a file is too big to edit, it 
should be split into more than one file of manageable size. The Filediv 
and File join utilities can be used for this. They are described in 
Chapter 10. 



The mouse is used to scroll the text in the window, move the insertion point, 
and select text to be cut or copied. Other operations, provided in five menus, 
are selected using the mouse. 



File Ed i t Search Type S ty le 



Print 



mmimimimmmimm&iimm^m^ 



□ 



I RHI^N.TEXT 



THE mmn 

Once upon a midnight dreary, v^fhile I pondered, weak and weary. 
Over many a quaint and curious volume of forgotten lore, 
1/Vlule I nodded, nearly napping, suddenly there came a tapping, 
hs of some one gently rapping, rapping at my chamber door. 
"'Tis some visitor/' I muttered, "rapping at my chamber door, 
"Only this, and nothing more. " 
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Figure 4-i. The Editor Display Window 

4.2 Using the Editor 

Start the Editor by pressing E in response to the Workshop command prompt. 
The Editor will prompt you -for a document name. If you want to edit an 
existing -file^ enter its name. I-f you want to create a new -fiie^ select Tear 
Off Stationery from the filing menu. The Editor will prompt you for the 
stationery name. Press RETURN for the default* which is blank paper. For 
more information on stationery > see below. 

The file that you are working on is called the active document. You may have 
several documents open and accessible at any one time* but only the active 
document may be edited. The active window is indicated by a darkened title 
bar. 

4.2.1 Editing Operations 

The basic editing operations are Cut* Paste* and Copy. To cut or copy text* 
you must first select the text to be cut or copied. Select text by moving the 
mouse while holding down the button. See section 4.3 below for complete 
information on selecting text. Text that is selected and cut is removed from 
the active document and placed in a special window called The Clipboard. 
Text that is copied is placed on The Clipboard and also left in place in the 
active document. 

The contents of The Clipboard may be inserted at any point in the active 
document by moving the insertion point to where you want the text inserted 
and selecting Paste from the edit menu. 

4.2.2 The Menus 

Operations are provided in five menus: File* Edit, Search, Type Style, and 
Print. The File menu is used to access things outside the Editor* such as 
documents and stationery. The Edit menu contains the editing operations. 
Search provides for finding strings in the active document. The Type Style 
menu selects the font for document display. The Print menu controls 
printing. Each of these menus is described in more detail below. 

You select an operation from a menu by moving the arrow pointer to the menu 
name on the menu bar and holding down the button. The menu is displayed. 
Select the menu item by moving the mouse up or down until the right item 
appears in reverse video. Releasing the button starts the operation. 

4.2.3 Creating and Using Stationery 

Stationery for a special purpose (such as a letterhead) can be created with 
the Editor. Stationery is ^st a regular document containing the desired 
text. To use any stationery other than the default blank paper* select Tear 
Off Stationery from the File menu* and type the name of the document 
containing the stationery when it asks you for the stationery name. 

To create stationery* make a document containing the standard text you 
want on the stationery. Save this document on the disk. To use this 
stationery* select Tear Off Stationery from the Edit -menu* and give it the 
file name of the stationery you created. 
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4.2.4 Editing Multiple Files 

More than one -file may be open at one time* but only one document is the 
active document. To read in a document when you already have an active 
document^ select Open from the File menu. It will ask you -for the document 
name. The new document will be read in to a window on the screen and will 
become the active document. To make another document the active 
documents use the mouse to move the pointer into a portion o-f that document 
and click. 

This capability may be used to copy text -from one file to another by using the 
following sequence of operations: 

• Open the document containing the text you want to copy. 

• Select the te>tt you want to copy and select Copy from the Edit menu. 
This places a copy of the text onto the Clipboard. You can use Cut if you 
want the text to be removed from its original file. 

• Open the document you want the text to be copied to. It becomes the 
active document. 

• Move the insertion point to the place you want the text to be inserted. 

• Select Pastes which will copy the text from the Clipboard to the active 
document. 

Further information on each of these operations may be found below. 

4.3 Selecting Text 

The basic editing functions are Cut» Copy> and Paste. Before you can Cut op 
Copy textf you must select the text to be cut or copied. Before you Paste » 
move the insertion point to where you want the text to be placed. You select 
text and move the insertion point by using the mouse to move the pointer on 
the screen. 

When there is an active document* the pointer will have one of two shapes: 

Text pointer in a document 

Arrow pointer for menus and scroll bars 

Use the mouse to move the pointer on the screen. The shape of the pointer 
will change when you move in and out of the document display window. 

Within the display window* the text pointer is used to move the insertion 
point and to select text. 

In selecting text* you may select characters* words* or lines. You may also 
select any number of characters* words* or lines. Selected text is displayed 
in re verse video. 

4.3.1 How do I Move the Insertion Point? 

The insertion point is indicated by a blinking vertical line where the next 
character will be inserted. All insertion* whether from typing or pasting* 
takes place at this point in the file* even if it is not visible in the window. 

To move the insertion point* move the text pointer to where you want it to be 
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and click. Note that the insertion point is also moved when you select text. 

4.3.2 How do I Select Characters? 

To select characters, move the text pointer to the beginning o-f the 
characters you want selected^ press and hold the button while moving to the 
last character you want selected. 

An alternate way o-f selecting characters, which is especially use-ful when 
selecting a large block of text, is as follows. Move the pointer to the 
beginning of the text you want selected and click. Then move the pointer to 
the end of the text you want selected and shift click (hold down the shift key 
on the keyboard and click the mouse button). You may use the scrolling 
controls to display the end of the text you want selected if it is too big to fit 
in the window. 

4.3.3 How do I Select Words and Lines? 

To select a word, move the text pointer into the word and click twice. To 
select a line, move the pointer into the line and click three times. 

To select multiple words or lines, click the required number of times, and 
hold. Move the pointer to the last word or line you want selected and release. 

An alternate method, especially useful when you want to select more text 
than will fit in one display window, is as follows. Click the required number of 
times to select the first word or line. Scroll the window if necessary to 
display the last item you want selected. Move the pointer to the last item you 
want selected, shift click, and the entire block of text will be selected, 

4.3.4 How do I Ad^st the Amount of Text Selected? 

To change the amount of text selected, move the pointer to the position that 
you want the selection to extend to and shift click. This can be used to either 
expand or contract the selection, 

4.4 Scrolling and Moving the Display 

When a document is longer than will fit into the display window, only part of 
the document is displayed at one time. You can change what part is displayed 
by "scrolling" through the display. The vertical bar on the right side of the 
active window is the scroll bar. An example of a text- window showing the 
scroll bar is in Figure 4-1. 

The display window can be changed in size and moved on the screen. This 
allows you to have multiple files displayed on the screen. These operations 
are done using the title bar and size control box. 

4.4.1 Scrolling the Display 

There are three ways of moving the display window through the document. 
The first is by using the elevator. The elevator is the white rectangle in the 
scroll bar. Its position in the "elevator shaft" (the grey portion of the bar) 
indicates the relative position of the currently display d text window in the 
document. If the elevator is near the top, you are near the beginning of the 
document. If it is near the middle, the text displayed on the screen is near the 
middle of the document, and soon. To change the position of the text window, 
you can use the mouse to move the arrow pointer into the elevator, click and 
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hold the button down while you move the elevator to the position in the 
document you want to display. When you release the buttonf the display will 
be updated to the new position. 

The second way of moving the window makes use of the view buttons. The 
view buttons are the boxes at each end of the elevator shaft. If you move the 
arrow pointer to a view button and clicks the display will move one text 
window toward the beginning or end of the documents depending on which 
button you clicked. 

The third way of moving the window uses the scroll arrows, which are ^st 
above and below the view buttons. If you move the arrow pointer to the 
bottom scroll arrow and click, the display window will move one line toward 
the end of the document. If you hold the button down, the window will 
continue to move a line at a time until you release it. The upper scroll arrow 
works the same way, except it moves the window towards the beginning of the 
document. 

4.4,2 Moving the Display 

You can move the display window on the screen and change its size. This lets 
you display multiple files on the screen. You can make any visible window be 
the active window by moving the pointer into it and clicking. 

To move a window, move the pointer to the title bar, press the mouse button 
and hold it while you move the window. When you release the button, the 
window will be redisplayed at the new location. 

To change the size or shape of the active window, move the pointer to the 
size control box, press the button, and move the pointer until the window is 
the right size and shape. Release the button and the resized window will be 
displayed. The size control box is the box in the lower right hand corner of 
the window. Only the active window can be resized. 

4.5 The File Functions 

The file menu provides functions for communicating with the outside world. 
Functions are provided for reading in and writing out documents, and for 
exiting the Editor. The Filing menu is shown in Figure 4-2. Each function is 
explained below. 

filingmenu 



Figure 4-2, The Filing Menu 
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Save L Put Away 

This writes out the active document and closes it. 

Save a Copy in ... 

This writes out a copy o-f the active document to another -file name. You are 

prompted for the name of the file to write to. 

Save & Continue 

This saves all changes made so far by writing out the document to diskt 

without closing the document. 

Revert to Previous Version 

This returns the document to the way it was before you started editing it, or 
when you last saved it. This is done by reading in the file from the disk. 

Open ... 

This tells the Editor to get a new document. It prompts you for the document 

name> then reads it in and makes it the active document. The Editor will 

supply the .TEXT extension on the file name. 

Duplicate ... 

This allows you to read in a copy of an existing document to edit into a new 
file. It is read in with the default name "untitled" 

Tear Off Stationery ... 

This gets a new piece of stationery and makes it the active document. See 
section 4.2.3 above for more information. The stationery is given the default 
name "untitled". 

Exit Editor 

This first asks you if you want to put away any modified documents. If you 
answer yes* they are written out to disk. Then it exits the Editor. 

The Edit Functions 

The Edit menu provides the editing functions and tab setting. It is shown in 
Figure 4-3. 

The three basic edit functions are Cut, Paste, and Copy. These make use of 
the special window called The Clipboard. The Clipboard can hold one piece of 
text. Text is put into The Clipboard by selecting it in the active document, 
and either cutting it or copying it. Text is copied from the Clipboard and 
inserted at the insertion point with the paste operation. 



\Mm i.axt Chanfje 



Cut 

Copy 

Paste 



#C 



Shift Left 
Shift Right 



«R 



Set Tabs ... 



Select fill of Document «fl 
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Figure 4-3. The Edit Menu 

For example^ to move a block of text from one place in a document to another^ 
follow these steps*. 

1. Select the block of text to be moved. 

2. Select Cut from the Edit menu. The text is removed from the active 
document and placed on the Clipboard. 

3. Move the insertion point to where you want the text to be. 

4. Select Paste from the Edit menu. The text on The Clipboard is inserted 
at the insertion point. 

The edit menu also allows you to adjust selected text left or right by 
inserting or deleting spaces. It also allows you to set tabs. 

Some edit functions may also be done by holding down (apple) and pressing 
another key. The key that corresponds to each function is shown in the edit 
menu. See figure 4-3. 

Undo Last Change 

This command puts the document back to the way it was before the previous 
operation if possible. The system will tell you if the last operation cannot be 
undone. 

Cut 

Cut places a copy of the currently selected text into The Clipboard and 
removes the text from the active document. You may also Cut by pressing 
(apple) X. 

Copy 

Copy places a copy of the currently selected text onto The Clipboards but 
does not remove it from the active document. You can also Copy by pressing 
(apple) C. 

Paste 

Paste inserts a copy of the text on The Clipboard at the insertion point in the 
active document. You can also Paste by pressing (apple) V. 

Shift Left 

Shift Left moves selected text left by deleting a single space from the left of 
each line. It will not delete any characters other than spaces. It is most 
often used to ad^st the left margin of a block of text. You can shift left by 
pressing (apple) L. 

Shift Right 

Shift Right is similar to Shift Left, except that it moves the selected text to 
the right by inserting spaces at the beginning of each line. This can also be 
done by pressing (apple) R. 

Set Tabs ... 

Set Tabs allows you to set the spacing of the tab stops. 

Select All of Document 
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You can select the entire 



This command selects the entire document, 
document by pressing (apple) A. 

4.7 The Search Functions. 

The Search menu gives you the ability to search -for a text string in the active 
document. The basic operation is Findf which locates the next occurrence of 
the string and selects it. Find & Paste All will replace each occurrence o-f the 
string with the contents of The Clipboard. Several options are provided to 
specify how the match isto be found. The Search menu is shown in Figure 4-4. 



Find ... Uf 

Find Same US \ 

Find & Paste Rll 



^Separate IdentiFiers 
Rll Occurrences 



VCases Need Not Agree 
Cases Must Rgree 



Figure 4-4. The Search Menu 
All searches start at the insertion pointy and go to the end of the file. 
There are three search operations in the Search menu, as follows: 

Find ... 

Find prompts you for the string to search for, then finds the next occurrence 
of the string. If a match is found, it will be selected and uispiayed. The Find 
command can also be executed by pressing (apple) F. 

Find Same 

Find Same repeats a previously specified Find, and selects the next 
occurence of the string. You may do a Find Same by pressing (apple) S. 

Find & Paste All 

This finds all occurrences of the specified string from the current insertion 
point to the end of the file, and replaces each of them with the contents of 
the Clipboard. 

The other, four items in the search menu tell how a match is to be found. 
There are two areas to describe*, searching for tokens or characters, and 
whether or not case must be matched. The options currently in effect have a 
check mark in front of them. To change the option, use the mouse to select 
the one you want. 

The first set of options tells whether to search for tokens or to search 
literally: 
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Separate Identifiers 

When Separate Identifiers is selected* the search operation will look for a 
"token" or word to match the search string. Only the first 8 characters are 
significant in a this type of search. 

All Occurrences 

When All Occurrences isselected# the search operation will match any string 
containing the same characters* even if it is only part of a word. 

The neMt options indicate if case is significant in finding a match: 

Cases Need Not Agree 

VJhen this item is selected, any string with the same characters will be a 
match* regardless of whether they are in upper or lower case. 

Cases Must Agree 

When this item is selected, the string must exactly match the search string, 
including case, to be selected. 

4.8 The Type Style Functions 

The Type Style menu allows you to change the display font. The Type Style 
menu is shown in Figure 4-5. A check appears in front of the font that the file 
is currently displayed in. You may change the font by selecting another font 
from the menu. 

The font selected will affect how many characters may be displayed on aline, 
and whether or not the display is proportionally spaced. When a file is 
printed, it will be printed in the same type style it is displayed in. 



20 Pitch Gothic 


15 Pitch Gothic 


VU Pitch Modern 


12 Pitch Elite 


10 Pitch Modern 


10 Pitch Courier 


PS Modern 


PS Executii/e 



Figure 4-5. The Type Style Menu 

4.9 The Print Functions 

The Print menu provides functions for printing a document. You can print all 
or part of a document, choose what form of footers are to be printed, specify 
if Pascal keywords are to be emphasized, and tell what type of printer is 
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being used. The Print menu is shown in Figure 4-6. 



Print fill of Document 
Print Selection 



VFuM Footers 
Page Numbers Only 



yPlain Keykvords 
Differentiated Keyw^ords 



v'Dot Matrix Printer 
PaperTiger Printer 



Figure 4-6. The Print Menu 
The Print -functions are as follows: 

Print AH of Document 

This command prints the entire document. 

Print Selection 

This command prints only the currently selected portion of the document. 

Both of the print commands will wait if the printer is not ready. 

The remaining options in the Print menu chose how the print is to be 
performed. They are organized into 3 sets of 2 options. The currently 
selected option in each set is indicated by a check mark. You can select any 
combination of options you want. 

The first options control v/hat type of footers will be printed at the bottom 
of the page. 

Full Footers 

When Full Footers is selected* Each page printed will have a footer 
consisting of the file name> the page number* and the date. 

Page Number Only 

Selecting Page Number Only results in only a page number on the bottom of 
each printed page. 

The next options are used for printing Pascal programs. 

Plain Keywords 

Selecting Plain Keywords makes Pascal keywords print with normal text. 

Differentiated Keywords 

Selecting Emphasized Keywords makes the printed output emphasize all 
Pascal keywords by underlining them. 

The next options select the type of printer to print pn. Select the type of 
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Dot Matrix Printer 
Daisy Wheel Printer 
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Cha.p±er5 
THE PASCAL. COMPILER 

5.1 The Pascal Compiler .....««....,... 5-2 

The Pascal compiler translates Pascal source statemeniis into object code. 
This translation is done in two steps. The source statements are -first 
translated into intermediate code (I-code)t then the I-code is translated into 
object code. 

5.2 Using the Pascal Compiler 5-2 

The compiler expects a text file containing a Pascal program as input. The 
compiler is executed by pressing P in response to the command prompt. The 
code generator^ which translates I-code into ob^ct code> is executed by 
pressing G. 

5.3 The Pascal Compiler Commands .................................... 5-3 

The compiler commands desired are entered into the Pascal source file. They 
provide for symbolic debugging information and conditional compilation. 

5.4 Further Information 5-3 

More information on using the Pascal language can be found in the Pascal 
Reference Manual for the Lisa . 
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TT M E R*^ S Ci^ L C OM R I L E R 

5.1 The Pascal Compiler 

The compiler iransla-tes Pascal source sla-tements into ob^ct code. This 
-translation is done in two steps. The first step (parsing) converts the 
program into semantically equivalent tree structures called I-code. The 
second step translates the resulting I-code into machine language. 

A complete definition of Lisa Pascal is found in the Pascal Reference Manual 
for the Lisa . 

The Pascal run-time support routines are in the library lOSPASLIB. After 
generating the object code^ it is necessary to link the program with 
lOSPASLIB before you can run it. For information on how to link the 
program^ see chapter 7 in this manual. 

5.2 Using the Pascal Compiler 

The compiler expects a text file containing a Pascal source program as input. 
You can create this text file using the Editor. 

When you have prepared a source program* use the Compiler to translate it 
into object code. Start the compiler by pressing P in response to the 
workshop command prompt. The compiler first asks for the 

Input file [ .text! - 

Type the name of the file that contains the source program. You do not need 
to add the .TEXT extension. The compiler then asks you for the 

List file - 

Type the name of the file that you want the listing to go to» or press RETURN 
if you don't want a listing. You can display the listing on the console by using 
the -console pathname. The compiler next asks you where to store the I-code 
form of the program: 

I-code file Kinput name>]C.I] - 

If you want the I-code to be. stored in a file with the same name as the source 
file, but with a .1 extension instead of the .TEXT, .just press RETURN. If you 
want another name, type the name and press return. 

After the last input, the compiler translates the program into I-code and 
stores it in the I-code file. If there were any errors, they will be displayed on 
the console. 

5.2.1 Using the Code Generator 

To translate the I-code into ob^ct code, press G in response to the shell 
command prompt. The code generator first asks you for the 

Input file [.13 - 

Type the name of the I-code file. You do not need to add the .1 extension. The 
generator then asks you for the 
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Output File C<iriput name)] [ .0BJ3 - 

To accep-t the default name> press RETURN. If you want a different name for 
the output file, type the name and press RETURN. The .OBJ extension will be 
added to the name for you. 

The output file from the code generator is object code, but it is not 
executable because it does not contain the Pascal run-time support routines. 
The run-time support routines are contained in lOSPASLIB. These routines 
must be added to the object file by using the Linker. See chapter 7 in this 
manual for more information on the Linker. 

5.2.2 Compiling with a Different Intrinsic Library 

The Compiler and the code Generator both access INTRINSIC.LIB, the library 
of intrinsic units. It contains information about the intrinsic units used by 
the program. If you want the program to be compiled with a different 
intrinsic library, you can enter "?" to the request for an input file in both the 
Compiler and the Generator. They will ask you for the name of the intrinsic 
library you want to use. After entering the name of the intrinsic library, the 
compilation proceeds in the usual way. 

5.3 The Pascal Compiler Commands 

Compiler commands allow control of code generation, input file control, 
listing control, and conditional compilation. The commands all start with a $, 
and are placed as comments in the source program where you want the 
command to take effect. A complete list of the compiler commands is found 
in the Pascal Reference Manual for the Lisa . 

5.4 Further Information 

For further information on the Pascal language, refer to the Pascal 
Reference Manual for the Lisa. A Pascal program can call assembly language 
routines. More information on assembly Language is in chapter 6 of this 
manual. 

The Debugger, described in Chapter S, can be used for run time debugging of 
Pascal programs. More information on the run time environment of a Pascal 
program is found in Chapter 6. 

The Operating System provides a number of routines that can be called from a 
Pascal program to perform various system functions. These routines are in 
the SYSCALL unit, which is described in the Operating System Reference 
Manual for the Lisa. 
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Cha-p-ten 6 

THE ASSEMBLER 

6.1 The Assembler 6-2 

The assemblertranslates6S000 assembly language into machine language. 

6.2 Using the Assembler 6-4 

The assembler is startedby pressing A in responseto the command prompt. 
It accepts a "text -file as inputs and produces a machine language (.OB J)f lie 
as output. 

6.3 The Assembler Opcodes ................................................ 6-5 

The assembler opcodes are the standard 6S000 opcodes^ with a tew 
alternate-forms -for some instructions. 

6.4 Assembler Syntax .«.........;.........«.......«......»«................ 6-7 

An assembler statement consistsot an optional label* the opcode* and one 
or two operands. The operandscan contain expressions. 

6.5 Assembler Directives .................................................. 6-9 

The assembler directives provide for procedure and "function definition* 
macros* label and constant declaration* listing control* storage allocation* 
and conditional assembly . 

6n6 Communication withPascal ..........................................6-11 
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THE ASSE M BLER 

6.1 The Assembler 

The assembler is a program that translatesassembly language source code 
into object code. The assembler accepts a text tile containing the source 
code as input^and produces an object file as output. 

The abject file produced must be linked with a Pascal main program before 
it can be executed. 

Assembly language routines are used to implement low level or time 
critical functions. Thischapter describeshow to use the assembier>and the 
syntax of assembly language programs. Information on the machine 
instructions available on the 6S000 processor is found in the Motorola 
manual. 

6.2 Using the Assembler 

To assemble a program^ pressA from the Workshop command line. Then 
specify the input file (the file that contains your source program) and two 
output files: the object file (the file that contains the machine-language 
code produced by the assembler) and an optional listingfile. 

The input file must be a text file containing assembly language source 
statements. You can make this file with the editor. The output file 
produced is an object file (.OBJ)tthat must be linked with a Pascal main 
program to be run. 

6.2.1 Assembler Options 

When you startthe assembler, the option settingsare displayed. You may 
change the optionsby responding to the input file prompt with "?". There 
are two asse mbler options: 

P Pretty Listing. 

S Print information about available space . 

Each option may be setto + or -: 

+ On 

Off 

When Pretty Listingison, the forv/ard jump addressesare filled in with the 
correct values. 

After setting any options desired, pressreturn^and the assembler asksyou 
for the name of the input file. The assembler then asks you for the name of 
the listing, and the output files. 

6.2.2 The Input File 

The input file is a text file containing assembler language source 
statements. A file created using the Editorwill be in textfile format. 

When the assembler asks you for the name of the input file, type "?" if you 
want to change assembler options at this time; otherwise type the 
pathname of your source file. 
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6.2.3 The Object File 

The objeci: .-file produced by the assembler contains a machine language 
■version o-f your source program. The name of an object -file ends with .OBJ. 
An object -file is not executable; it must be linKed with a Pascal program 
thatcalls it. See Section 6n6 for-furtherintormation. 

The output file will be an object file which must be linKed with a Pascal 
main program before itcan be executed. 

6.2.4 The Listing Fi le 

The listing file produced by the assembler contains a list of source 
statementsand their machine-language equivalent. If Pretty Listing isof ft 
all addresses for forward referencing branches will be displayed as 
asterisK5("*-*^-J^*).If Pretty Listing is ont the actual value will be filled in. 

Source statement errors are flagged in the listing. Refer to the Appendix 
for a listof assembler error messages. 

An example of an assembler listingfile isshown in Figure6-i . 
assembler] istinq 



TAIL MC -- 

PAGE - 5 ASMSTR 



FILE: EX/ASM/STR. TEXT 



OOOOl 

OOOOl 205F 
00021 225F 
00041 2F0A 
00061 



00061 
OOOAl 
OOOCI 
OOOEi 
OOOEl 
OOlOl 
00121 
00161 



45FA 0016 

4280 

1012 

12DA 
5340 

6500 0006 
12DA 



00181 50F6 
OOlAl 



OOlAl 
OOlCl 
OOIEI 
OOlEl 
OOlFl 
00261 
002DI 



245F 
4ED0 



26 



. proc 
move. 1 
move. 1 
move. 1 

lea 
dr. 1 
move. b 

move. b 
copy subq 
bio 

move. b 
bra 

done move. 1 



AsmStP 
(a7) + ,aO 
(a7)+,al 
a2,-(a7) 

s ize, a2 

dO 

(a2),d0 

(a2)s(al). 

«l,dO 

done 

(a2)*.(al)* 

copy 



37)+,a2 
.0) 



74 68 69 73 20 73 74 myStr 
72 69 6E 67 20 69 73 
20 66 72 6F 6D 20 74 

00341 68 65 20 4C 49 53 41 

003BI 20 61 73 73 65 6D 62 

00421 50 65 72 

00451 00 

00461 

00461 

00461 ; 

00461 



.byte 
. asc i i 



. a 1 ign 



38 

' this 



return address 

address of string passed From Pasca I pgm 

save scratch reg a2 



get size of string 

copy size of string (first byte of string) 

done copying string? 

yes, return to pascal 

copy one char of the string 



restore scratch reg 
return to pasca I 



string is from the LISA assembler' 



just to be sure next instruction is on word 
boundary (even address) 



Figure 6-i. Assembler Listing 
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H you speci+y a device name such as -PRINTER or -COMSOLEtorthe listing 
-file? the listing will be printed on that device. Ifyou specify a.disk-file^the 
listing will be created asa text-file;you may thenprintitby using the Copy 
command in the File Manager command line. 

6.3 Assembler Opcodes 

The 6S000 opcodes are described in the Motorola MC6S000 Microprocessor 
User's Manual. The assembler has two variant mnemonics for branches 
(BHS for BCC and BLOforBCS). The variant names are more indicative of 
how the instructionis being used after unsigned comparisons. The default 
radix isdecimal. 

The size of an operation (byte* wordror long) is specified by appending 
either. Bf.W^ or .L to the instruction. The defaultoperationsize is word. To 
cause a short forward branch* append a .S to the instruction. The default 
branch size isLong. 

6.3.1 Optimization 

It should be noted that the Assembler accepts generic instructions and 
assembles the correct form. The instruction ADD^ for example^ is 
assembled into ADD, ADDA^ ADDQ* or ADDI* depending on the context. 

ADD D3,A5 

becomes ADDA D3,A5. 

MOVEfCMPt and SUB are handled in a similar manner. 

6.4 Assembler Syntax 

This section describes the form in which the assembler expects an 
assembly language program. We describe the structure of an assembly 
language program in section 6.4.1. We then describe the form of constants? 
identifierstlabels^expressionsjandhow to specify addressingmodes. 

6.4.1 Structure of an Assembly language Program 

An assembly language program contains one or more procedures or 
functions. The structure of an assembly language source file looKes like 
Figure 6-2. First it contains an (optional) section of non code generating 
operations. This is usually where any constants or macros are defined. 
Nextitconainsone or more procedures (.PROC) or functions(. FUNG). These 
each contain a sequence of code generating operations and directives. A 
procedure or function is ended when the assembler encounters the next 
.PROC or .FUNC. A .END directive is the last statement in the program. 
Any textbeyond the .END is ignored. 
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noncode generating operations 

.PROC (or.FUNC) 

code generating operationsand any dlrectivesneeded 

.PROC 



etc. 

.END 

Figure 6-2. Structure of an Assembly Language Program 

The noncode generating directivesare: 

.EQU -MACRO .IF .LIST .MACROLIST 

,ENDM .ELSE .MOLIST .NOMACROLIST 

.REF .ENDC .PAGE .PATCHLIST 

.DEF .TITLE .NOPATCHLIST 

6.4.2 Constants 

Constantsin the Assembler can be either numeric or stringconstants. 

d. 4.2.1 Numeric Constants 

Numeric constants in the assembler can be expressed in decimal* 
hexadecimalt octal* or binary. The defaultradix isdecimal . The other three 
basesare expressedas follows: 

HeKadecimal 

Hex numbers can be expressedin two ways: 

1. Preceed the number with a "$"- Examples of thisare: 

$FFi3 
$127 

2. Follow the number with an "H". Using this form, the number must 
startwith a digit (0-9). Examples: 

OFFISH 
i95H 

Octal 

Octal numbers are followed by the character "O" . Note that thisisthe letter 

0,not the character zero (0). Examples: 

770 
104O 
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Binary 

Binar-ynumbers aretoilowedby thecharacter "B".EKamples: 

iOilB 
lllOOOB 

6.4.2.2 String Constants 

String constants are delimited by matching pairsot single or double quotes. 
E X ample s of stringconstants are : 

"thisisastringconstant" 
'usingsinglequotesasdelimitersletsyou include "double" quotes' 

6.4.3 Identi-fiers 

Only the -first eight characters of identifier names are meaningful to the 
assembler. The first character must be alphabetic; the rest must be 
alphanumeric^ period^underbartor percent sign. 

Examples of identifiersare: 

LOOP 

EXIT_PRC 

MUM 

ft 

6.4.4 Labels and Local Labels 

Labelsbegin in column one. They can be followed by acolon* if you like. 

Local labels can be used to avoid using up the storage space required by 
regular labels. The local label stack can handle 2i labels at a time. It is 
cleared every time a regular label is encountered. Local labels in this 
assembler start with the character 9. A local label is an '3 followed by a 
stringof decimal digits(0-9). Examplesof local labelsare: 

3123 

Q2 

379 

6.4.5 Expressions and operators 

All quantities are 32 bits in size unless constrained by the instruction. 
Expressionsare evaluated from left to right with no operator precedence . 
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/ 



Angle brackets can be used to control expressione valuation. The following 
operatorsare available: 

+ unary or binary addition 

unary minus or subtraction 

ones complement (unary operator) 

exclusive or 

multiplication 

division(DIV) 
\ MOD 

I logical OR 

& logical AND 

= equal (used only by J F) 

< > not equal (used only by .IF) 

There is no operator precedence in expressions. For example^ in the 
expression 2 + 9 -& 4, the addition is performed first. To make the 
multiplication be performed first^the expressioncan be rewritten with 
brackets to show precedence: 2 + <9 * 4>, or the operands can be reordered 
a5:9^4 + 2. 

6.4.6 Addressing Modes 

The following is a summary of the addressing mode syntax for the 6S000. 
Refer to the Motorola 6S000 manual for information on the addressing 
modes supported by the 6S000. Table 6- i gives a summary of the 
addressingmodes including theirsyntax. 

Table 6-1. Summary of Addressing Modes 



ode 


Register 


Syntax 


Meaning 


Extra Words 





0..7 


Di 


Data direct 







1 


0..7 


Ai 


Addressdirect 









0..7 


(Ai) 


Indirect 







3 


0..7 


(Ai)+ 


Postincrement 







4 


0..7 


-(Ai) 


Predecrement 







5 


0..7 


e(Ai) 


Indexed 




1 


6 


0..7 


e<Ai,Ri) 


O-f-fsetindexed 




i 


7 





e 


Ab solute short addre ss 


. i 


7 


1 


e 


Absolute long address 


2 


7 


2 


e 


PC Relative 




1 


7 


3 


e<Ri) 


PC Relative inde; 


<ed 


1 


7 


4 


#e 


Immediate 




lor 2 



Notes: 

1) The indexed and PC relative indexed modes are determined by the 
opcode. 

2) The absolute address and PC relative addressmodes are determined by 
the type of the labeKabsoluteor relative). 
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3) The absolute shor-t and long address modes a^re determined by the size o-F 
the operand. Long mode is used only tor long constants. 

4) The number of extra words tor immediate mode is determined by the 
opcode size modi-fier (.Wor.L). , 

6.4.7 Miscellaneous Syntax 
Comments 

A semicolon begins a comment in an assembly language program. All 
characters on a line atter a semicolon are ignored. Thisis an example of 
comments: 

; Th i s i 5 a comment on a line by itselt 

CLR.L DO ;comment atter a statement 

Current Program Location 

The current program location is indicated in assembly language by the 
symbol "*". Examples otitsuse are: 



JMP 
JMP 



*-4 



Loop i nf i n i tl V 
Jump back 4 bytes 



Move Multiple (MOVEM) 

To specif y which registersare affected by Move Multiple (MOVEM)>specify 
ranges of registers with "-'Sand specify separate registerswith 'V". For 
ex ample J to push registersDO through D2t D4j and AO through A4 onto the 
topof the stack: 

MOUEM.L D0-D2/D4/A0-A4,-(A7) 

6.5 Assembler Directives. 

The Assembler directives (pseudo-ops)are: 

begin procedure with Expr args 

begin function with S x pr args 

make identifiersexternallyavailable 

declare externalidentifiers 

put following code in segment 'name' 

end of entire assembly 

place ASCII string in code 
allocate a byte in code for each value 
allocate length by tesof value 
allocate a word for each value 
allocate a long word for each value 
allignnext code on multiple of Expr 

place next byte at (value > 
same as .ORG 

set label equal to < value > 



.PROC 


<ideni:i'fier>C,E;!pr3 


.FUNC 


<identi-fier>CfExpr3 


.DEF 


(iden-tifier-list)- 


.REF 


<identi-fiBr-lis"t> 


.SEG 


'<name>' 


.END 


^ 


.ASCII 


'< char acter-string > 


.BYTE 


<value-list> 


.BLOCK 


< length >[ rvalue 3 


.v;oRD 


< value-list > 


.LONG 


<value-list> 


.ALIGN 


<Expr> 


.ORG 


< value > 


.RORG 


< value > 


.EQU 


< value) 
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.MACRO 
.EMDM 



(identifiers- 



begin macro definition 
end macro definition 



.IF 

-ELSE 

.ENDC 



<.expr.> 



.LIST 

.NOLIST 

-PAGE 

.TITLE '<title>' 

.MACROLIST 

.NOMACROLIST 

.PATCHLIST 

-HOPATCHLIST 

.INCLUDE <filename> 



begin conditional assembly 
optional alternate to .IF block 
end conditional assembly 

turn on assembly listing 
turn off assembly listing 
issuea page feed in listing 
title of each page in listing 
turnon macro expansionlisting 
turn of f expansionlisting 
turnon patchlist 
turn off patchiist 

insert< filename)- into assembly 



6.5.2 Space Allocation Directives. 

The space allocation directives are .ASCII, .BYTEt .WORD, .LONG, and 
.BLOCK. 

.ASCII 'string-' 

converts 'string'into the equivalent ASCII byte constants and places the 
bytesin the code stream. The string delimiters must be matching singleor 
double quotes. To insert a single quote intothe code use double quotes as 
delimiters. Similarly for double quotes: 



.ASCII 
.ASCII 



"AB-'CD" 
'"AB"CD' 



; string containing a. -single quote 
5 string containing a double quote 



.BYTE < values)- 

allocates a byte of space in the code stream for each of the values given. 
Each value must be between -128 and 255. 

.BLOCK <aength>C,value] 

allocates -(length)- bytes, each filled with the value given. If no value is 

given, a block of zeros is allocated. 

.WORD < values)- 

allocates a v^ord of space in the code stream for each of the values listed. 
The valuesmust be between -32768 and 65535. 
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Forexampie^ 

TEMP .WORD 0,65535,-2,17 

creates the assembled output: 

Oi300 
FFFF 
FFFE 
0011 

.LONG <;value5> 

allocates two wordsot space foreach value in the list. Forexamplej 

STUFF .LONG 0,65535,-2,17 

createsthe output: . 

00000000 
OOOOFFFF 
FFFFFFFE 
00000011 

<lab8l> .EQU <value> 

assigns<value> to<labei>. <value> can be an eKpressioncontaining other 
labels. 

.ORG < value > 

puts the next byte of code at <value> relative to the beginning o-f the 

assembly file. Bytes of zero are inserted from the current location to 

<value>. 

.RORG 

is similar to .ORG. It indicates that the code is relocatable. Because the 
loader does not support absolute loading^ .ORG and .RORG accomplish the 
same function. All addressing must be PC relative. 

RORG (without the leading period) is the same as .RORG. Similarly > END = 
.SND,EQU = .EQUIPAGE =".PAGE, LIST= .LIST,MOL= .NOLIST. 

6.5.3 Macro Directives. 

A macro consistsof a macro name* optional arguments* and a macro body. 
When the assembler encounters the macro name* it substitutesthe macro 
body for the macro name in the assembly text. Wherever Xnoccurs in the 
macro body (where n is a single decimal digit)* the text of the n-th 
parameter is substituted. If parameters are omitted* anuU stringisusedin 
the macro expansion. A macro can invoke other macros up to five levels 
deep. In the assembly listing* the listing of the expanded macro code is 
controlled by the options .MA(:R0LIST and .NOMAGROLIST. These options 
are described in Section 6,5.5. 
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.MACRO (identifier) 



.ENDM 

defines the macro named <identifier>. The following is an ej^ample 
of a macro: 



.MACRO 


Help, 


HOME 


%1,D0 


ADO 


D0,X2 


.ENDM 





If 'Kelp'' is called in an assembly with the parameters 'Alpha' and /Beta'tthe 
listingcreated would be: 

Help Alpha, Beta 

# MO^E Alpha, DO 

# ADD DO, Beta 

6.5.4 Conditional Assembly Directives. 

The conditional assembly directives .IF^ .ELSE* and ,EMDC are used to 
include or exclude sections of code at assembly time based on the value of 
some expression. 

.IF <e5<pre55ian> 

identifiesthe beginning of a conditional block. <expression>isconsidered 
to be false if it evaluates to zero. Any non-zero value is considered true. 
The expressioncan also involve a test for equality (usingO or =). Strings 
and arithmetic expressionscan be compared- If <expression>is false,. the 
Assembler ignores code until a .ELSEor.ENDC isfound. The code between 
the optional .ELSE and -EMDC is assembled if -(expression;- is false. 
Otherwiseitisignored.Conditionals can be nested. The macros HEAD and 
TAIL given in section 6.6-1 provide examples of the use of conditionals. The 
general form is: 



.IF -(expr) 



jassembled if -(expr) is true 



[.ELSE] joptional 

^assembled if <expr> is false 

,ENDC 

6.5.5 External Reference Directives. 

Separate routines can share data structures and subroutines by linkage 
between assembly routines using .DEF and .REF. These directives cause 
the Assembler to generate link information that allows separately 
assembled assembly routines to be linked together. .DEF and .REF 
associate labels between assembly routines^ not between assembly 
routines and Pascal.The only way to communicate data between Pascal and 
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assembly routines is by using the stack. This is done by passing them as 
parameters in the procedure or function call. Information on parameter 
passingbetween Pascal and assembly language isfound in section 6.6. 

.DEF <identifier-list> 

identifies labels defined in the current routine as available to other 
assembly routines through matching .REFs. The .PROC and .FUNC 
directives also generate code similar to that generated by a .DE F with the 
same name^ so assembly routines can call external .PROCs and .FUMCs 
vAth.REFs. 

.PROC Simple,! 

.DEF Alpha, Beta 



BME • Bete 



Alpha HOUE 

RTS 
Beta MOVE 

RTS 
.END 

This example defines two labels* Alpha and Beta? which another assembly 
routine can access with .REF. 

.REF <identif ier-1 ist> 

identifies the labels in <identifier-list>used in the current routine as 
available from some other assembly routines which defined these 
identifiersusingthe .DEF directive. 

.PROC Simple 
.REF Alpha 



JSR Alpha 

.END 

usesthe label 'Alpha' declared in the .DEF example. 

When a .REF is encountered* the assembler generates a short absolute 
addressing mode for the instruction (the opcode followed by a word of O's) 
and a short external reference with an addresspointer to the word of O's 
following the opcode. If the referenced label and the reference are in the 
same segment module* the Linker changes the addressing mode from short 
absolute to single-word PC relative. If jhowever^the referenced procedure 
is in a different segments the Linker converts the reference to an indexed 
addressing mode (off A5) and the word of zeros isconverted into the proper 
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entry offsetin the jump table-. If the referenced procedure is in an intrinsic 
unit (and therefore in a differentsegment), the lUJSR^ lULEA^IUJMP^ and 
lUPEA instructionsare used (seepage ##). The Linker blindly assumes that 
the word immediately before the word of zeros is an opcode in which the 
low order6 bitsare the effective address- Thusta .RE F label cannot be used 
with any arbitrary instruction. The .REF labels are intended for JBRf JUPt 
PEA^ and LEA instructions. 

.SEQ 

default segment name is" " (8 blanks). .SEG "segment name" putsthe 

code in segment called "segment name". 

6.5.6 Listing Control Directives. 

The directives that control the Assembler's listing file output are .LIST, 
.NOLIST,.PAGE, .TITLE,. MACROLIST^ .NOHACROLIST, .PATCHLIST, and 
.NOPATCHLIST. If you do not specify a name for the listingfile in response 
tothe Assembler'sprompt: 

Listingfile «cr> for none) - 

the listingdirectivesare ignored. 

Thedefaultfortheassemblerisfor.LISTMMACROLIST^and .PATCHLISTto 
be in effect when the assembler starts.. TITLEdefaultsto blank. 

.LIST and .NOLIST 

can be used to select portionsof the source tobe listed. The listinggoesto 

the specified output file when .LIST is encountered. .MOLISTturnsoff the 

listing. .LIST and .NOLIST can occur any number of times during an 

assembly. 

.PAGE 

insertsa page feed into the listingfile. 

.TITLE '<:title>' 

specifies a title for the listing page. <title> can contain up to SO 

characters, and can be enclosed in either single or double quotes. 

• TITLE -'Interpreter'" 

placesthe word, Interpreter,atthe head of each page of the listing. 

.PATCHLIST 

patches the forward referenced labels in the listing. It must be on if you 
want pretty listing. 

.NOPATCHLIST 

turnsoff patching of forward references. 

.MACROLIST 

turnson listingof the expanded code from a macro. 
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.NOMACROLIST 

turns ot-f listing o-f macro expansion. See Figure 6-3 for examples of the 
macro listingoptions. 



00241 
















tai i 4, ' 12345575' 


00241 


4E5E 












» 


UNLK A6 


00261 














» 


.IF 4=0 


00261 














# 


.ELSE 


00261 














tt 


.IF 4=4 


00261 


2E9F 












» 


MOVE.L {spy, (SP) 


00281 


4E75 












» 


RTS 


002AI 














u 


. Fl SF 


002AI 














tt 


-ENDC 


002AI 














it 


. ENDC 


002AI 


31 32 


33 


34 


35 


36 


37 


tt 


.ASCII '12345578V 


00311 


38 












tt 




00321 


4E71 














nop 


00341 


















00341 
















. nomacrolist 


00341 
















head 


00381 


















00381 


















00381 
















. inc lude ax/a; 



Figure 6-3. Macro Listing Options 

6.5.7 File Directives. 

The pseudo-op 

.INCLUDE <filename> 

causes the contents of < filename)- to be assembled at the point of the 
JMCLUDS. <filename> need not specify the ,TSXT suffix, An included file 
cannot itselfcontain a .INCLUDE statement, 

6,6 Communication with Pascal. 

Pascal programs can call assembly language procedures. The Pascal 
program declares the assembly language procedure or function to be 
EXTERNAL. If the assembly routine does not return a value ^ use .PROC. If 
.FUNC is used> space for the returned value is inserted on the stack just 
before the function parameters, if any. The amount of space inserted 
depends on the type of the function. A Longlntor Real function resulttakes 
two words^a Boolean resulttakes one word with the resultin the high order 
byte, and other types take one word. In the fallowing example, we link a 
bit-twiddling assembly language routine into a Pascal program. The Pascal 
host file is: 

PROGRAM BITTEST; 
MAR I, J; INTEGER; 
FUNCTION land < i , j j INTEGER ) ; INTEGER; 

EXTERNAL; (* ex ternal = Assembl y 1 anguage *) 

BEGIN 

i := 255; 

J :=33; 

WRITELN <I,J,-' AND = 
END . 



jiand (I , J)) ; 
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.FUNC 


IAND,,2 


; two arguments 


MOUE.L 


(A7)+,A0 


; return address 


MOME.W 


';A7)+,D0 


; J 


MOVE.W 


';A7)+,D1 


5 I 


AND.W 


Dl ,D0 


; I AND J 


NOVE.W 


D0.<A7) 


;put-function result 


JMP 


(AO) 




.END 







on stack 



In -the example given above we have made litile attempt io make the 
assembly language pracedure mimic the structureDt a procedure generated 
by the Pascal Compiler. A complete description of this structure requires 
some preliminary discourse. 

6.6.1 The Run Time Stack 

Automatic stack expansion code makes procedure entries a little 
complicated. To ensure that the stack segment is large enough before the 
procedure is entered, the compiler emits code to 'touch' the lowest point 
that will be needed by the procedure. If we 'touch' an illegal location 
(outside the current stack bounds)»the MMU hardware signals a buserror 
that causes the 68000 to generate a hardware exception and passcontrol to 
an exception handler. Thiscode, provided by the operating system, must be 
able to restore the state of the world at the time of theexception^ and then 
allocate enough extra memory to the stack that the original instructioncan 
be re-executed without problem. To be able to back up, theinstructionthat 
caused the exception must not change the registers, soa TST.W instruction 
with indirect addressingisused. 

In the normal case, the procedure's LINK instructionshouldbe preceded by 
a TST.W e(A7) which attempts to reach the stack location that can 
accomodate the static and dynamic stack requirementsof the procedure. If 
the static and dynamic stack requirements of your assembly language 
procedure are lessthan 256 bytes, you can assume thatthe compiler's fudge 
factor will protect the assembly language procedure, so the TST.W can be 
omitted. If the requirements are greater than 32K bytes, e(A7) may not be 
sufficient because only 16 bits of addressability are available (the 63000 
does call a i6-bit processor). In this case, the compiler currently emits 
cods something like: 

MOVE.L A7,A0 

SUB.L #Si2e,A0 ;#si 2e=dynaiTii c + static needed 

TST.W CAO) 

If the compiler option D+ is in effect (the default), the firsteight bytesof 
the data area following the final RTS or JMP (AO) contain the procedure 
name. LisaBug gets the procedure name from thisblock, making debugging 
much more pleasant. The following example is provided to show how an 
assembly language programmer can provide LisaBug with all the 
information it needs to perform fully symbolic low level debugging. 
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; ASSEMBLY LANGUAGE EXAMPLE 

DEBUGF ,EQU 1 
proc names 



. tru9 => allow debugging wjth 



HEAD — This MACRO can be used to signal the 
beginning o-f an assembly language procedure. HEAD 
should be used when you do not want to build a stack 
frame based on A6, but do want debugging information. 

No arguments 



.MACRO HEAD 
.IF DEBUGF 

LINK A6j#0 
.ENDC 

.ENDM 



fancy NOP used by debugger 



TAIL — This MACRO can be used as a generalized exit 
sequence. There are two cases. First j if you build 
a stack frame, TAIL can be used to undo the stack 
frame, delete the parameters (if any) and return. 
Second, if you do not want to build a stack frame 
based on Ao, this MACRO can be used to signal the 
end of an assembly 1 anguage procedure . In either 
case if DEBUGF is true, the Procedure_name 
is dropped by the MACRO as an 3-charac ter name. 

Two arguments: 

1) Number of bytes of parameters to delete 

2) Procedure Name as strinq exactly 8 characters 



.MACRO TAIL 
UNLK A6 
.IF :/.! = 

RTS 
.ELSE 

.IF VA = 4 

MOME.L <A7)+,<A7) ; 4 bytes of parameters 
RTS 
.ELSE 

MOME.L (A7)+,A0 
ADD.y #'a,A7 
JMP (AO) 
.ENDC 
.ENDC 



; bytes of parameters 



; put return addr into AO 
\ remoue params from stack 
; return to cal 1 er 
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.IF DEBUGF 

.ASCII r/.2 
.ENDC 
. EMDM 

The -f ol 1 ow j ng example demonstrates the use o-f the 
TAIL macro tor the purpose ot debugging. The example 
assumes that you want to build a stack frame based 
on A6. In a real assembly language procedure the 
zeroes below would be replaced by the local size and 
parameter size. 



; zero bytes ot locals 

; body ot procedure 

II zero bytes ot parameters 



.PROC SIMPLE, 

LINK A6,M0 

MOP 

TAIL 0,' SIMPLE 

. END 
These macros are sutticient tor the programmer writing small assembly 
language routinesto be called trom Pascal. 

Upon entry to the assembly routine^the stack is as shown in Figure6-4. 



(m , 



Callers stack Frame 



Callers Dynamic Unk 



Function Result 



Procedure Arguments 



Static Link 



Return Address 



Dynamic Link 



Local Frame 



Dynamic Requirements 



Hgn Memory 



Low Memory 



Figure 6-4. The Pascal Run Time Stack 

The function result is present only it the Pascal declaration is tor a 
function. It is either one or two vv'ords. If the result fits in a single byte (a 
boolean^ for example)^ the most significant half (the lower addressedhalf) 
getsthe resultvalue. 

Parameters are present only if parameters are passed from Pascal. They 
are pushed on the stack in the order of declaration; All reference 
parameters are represented as 32 bit addresses. Value parameters less 
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than 16 bltsinsize always occupy a -full word. All non-set value parameters 
larger than 4 bytes are passed by reference. It is the procedure's 
responsibilityto copy them. All large setvalue parameters are pushed onto 
the stacK by the calling routine. 

The static link is present only if the external procedure's level of 
declaration is not global. The link is a 4 byte pointer to the enclosing static 
scope- 
It is the responsibility of the assembly language procedure to deallocate 
the return address^the static link (if any), and the parameters (if any). The 
SP must point to the function result or to the previous top of the stack upon 
return. Regi5ter5D4 through D7 and A3 through A7 must be preserved.Itis 
recommended that you also preserve D3 and A2. 

6.6.2 Register Conventions 

The following are the registerconventionsused in the Lisa system. Itisthe 
responsibilityof the programmer to preserve these registers. 

D0-D2/A0-A1 : Scratch registers (can be clobbered) 

D3 jA2; Scratch regi sters, but shoul d be preserved 

D4-D7/A3,A4i Used for code opt imi zat ion 

A5: Pointer to user global s (must be preserved) 

A6; Pointer to base of stack (must be preserved) 

SP; Top of stack 

RegistersDS and A2 may be used at some time in the future by the compiler 
for code optimizationt so the assembly language programmer should 
preserve them also. 

6.6.3 Assembly Language Examples 

The following examples show how to use certain featuresof the assembly 
language. 

The first example illustrates the use of .REF and .DEF. These two 
directives allow an assembly language routine to reference another 
assembly routine. 

The Pascal host file is: 

program WasteTime; 

procedure Wait (time : integer)? 

external ; 
begi n 

writeln ("'Going to waste some time*'); 

wai t (50) ; 

writeln ( 'Fi n i shed wast i ng time'); 
end. 
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The assembly language file is: 

.proc wai t 

.ref eycle ; need to use a piece of code 

; whose entry point is cycle 

; defined outside procedure wait 

.ref more^time ; another outside procedure 

moMe.l (■5''7)i,aU ; return address in aO 

move.w (a7)+,dO ; need to wai t th i s many cycles 

; a parafTieter for cycle 

jsr cycle 

jsr more_time ; waste more time 

jmp (aO) ; return 

; the subroutine used by wait is defined in the 
; following code, this proc could do other things 
; besides the cycle routine 
.proc def_cycle 

; cycle visible to other procs 



; example of a line of code 

; beginning of the cycle routine 

; parameter i s in dO 



more code can qo here 



.def 




cyc]e 


J Ci 


ode 


can go here 


nop 






ycl e 






sub 




#1 ,dO 


bne 




cycl e 


rts 







31 



.proc 


more time 


clr 


dO 


add 


tt2,dO 


bne 


31 


rts 





; waste more time 
; use dO as timer 



.end 

The following program illustrates how to pass a Pascal string to an 
assembly language program* modify the string ^and returnit, Pascal strings 
have theirlengthstoredasthe firstbyte in the string. 

.proc AsmStr 

moMe.l CA7)+,A0 jreturn address saved in AO 

moMe.l (A7)+,A1 ^address of string from Pascal 

moMe.l A2,-(A7) ;saMe scratch register A2 
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lea 


sl2e,A2 




clr.l 


DO 




iTioye .b 


<A2) ,D0 




move .b 


(A2)+,(A1)+ 


copy 


subq 


#1 ,D0 




bio 


done 




moMe .b 


(A2)+,<A1)+ 




bra 


copy 


dorie 


rrio«.;e . 1 


<A7)+,A2 




jmp 


<A0) 



iget size oi string 

;copy si ze o-f str i nq 
jdone copying string? 
;yes, return to Pascal 
;one char of str i ng 



;restore scratch register 
jreturn to Pascal 

size .byte 38 

myStr .ascii "this string is from the LISA assembler*' 
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Cha.pi:er7 
THE LINKER 

7.1 The Linker 7-2 

The Linker is a program that .combines abject files to create an executable 
file. 

7.2 Using the Linker 7-3 

The Linker is started by pressing "L" in response to the Workshop command 
prompt. Inputs to the Linker are object files* command files* or options. 

7.3 The Linker Options 7-3 

The Linker options control how a link is performed. A list of the current 
option settings is displayed when you enter a "?" to the input file prompt. 

7.4 How do I Link a Main Program? 7-4 

A main program is linked by giving the Linker the object file from a Pascal 
program* along with all assembly language routines* compiled units* and 
libraries that the program uses. 

7.5 Regular and Intrinsic Units ........................................ 7-5 

Regular and intrinsic units are both are Pascal units* separately compiled. A 
regular unit is linked with a main program* and becomes part of the 
executable file. An intrinsic unit is shared among all programs that use it* 
both on disk and in memory. 

7.6 The Linker Listing 7-6 

The Linker listing provides a summary of the linking process and resources 
used. Optionally you can request lists of all symbols used. 

7.7 Resolving External Names ............................ «..«.......«. 7-7 

External names are symbolic references to separatly compiled modules. The 
Linker maps them to real addresses. 

7.8 Module Inclusion .................................................. 7-7 

The Linker only includes modules that are actually referenced. 

7.9 Segmentation ..................................................... 7-7 

Segmenting a program allows portions of it to be swapped out of memory when 
they are not being used. Segmentation is controled by a combination of 
compiler commands and Linker options. 

7A9 Error Messages ................... . . ............................. 7-8 

There are three types of error messages: warnings* errors* and fatal errors. 
They are listed in Appendix A. 
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THE LIMKER 

7,1 The Linker, 

The Linker combines object -files. Its input consists o-f commands and object 
files. Its output consists of object filest link-map informationt and error 
messages. The output of the Pascal compiler must be linked with lOSPASLIB 
before it can be executed. Other object files> including intrinsic unit 
libraries! and object files produced by the Assembler > can also be linked into 
the output object file. 

What the Linker does is as follows. When a program is compiled into an object 
file^ it contains the following sorts of things*. 

• Ob>ct code> similar to machine language » that expresses the algorithm of 
the program. 

ft Symbolic (named) addresses of all code whose location was unknown to the 
compiler. These include externally compiled routines (units and intrinsic 
units) and the Pascal library support routines (PASLIB). 

• Other information to be used by the Linker. 

The purpose of the Linker is to connect up all the necessary things (linking 
them together)^ and output an object file that can be executed. 

The Linker does this by going through the main program > and* each time it 
finds a symbolic address* it looks up that address in all the units and libraries 
it was given as input > and converts the symbolic address into a real address 
that will be correct when the program is loaded to be executed. 

If the Linker can't find something that is addressed symbolically > this is an 
error. An error message will be printed^ indicating the missing module. This 
process of finding the real addresses that correspond to the symbolic 
addresses is called resolving the external references. 

The Linker expects to find the file INTRINSIC.LIB even if you are not using 
any intrinsic units. INTRINSIC.LIB is a directory of libraries and intrinsic 
unitSf and includes information for the use of the Linker. INTRINSIC.LIB 
defines all the intrinsic units supplied with the Workshop system. 

7.1.1 Creating an Executable File, 

To create an executable file* the Linker must have the following inputs: 

• the ob^ct file from a main Pascal program. 

• object files for all external procedures referenced by the main program. 
These may be as Pascal units* assembly language routines* or intrinsic 
units defined in INTRINSIC.LIB. 

• All units used by the units the main program uses. 

• lOSPASLIB to provide the standard Pascal procedures and functions. 

The Linker combines these files and creates an executable object file. If it is 
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unable to link these files correctly to create a legitimate output filer the 
Linker will display an error message. If there is an error^ the object file 
produced is not executable. 

When linking a main program ^ all references to external objects must be 
resolved. Partial links are not allowed. 

While it is linking the program* the Linker does a "dead code analysis" and 
does not include any routines that are not referenced. Unnecessary routines 
are eliminated from the main program ♦ and from the units and libraries given 
as inputs to the link. 

?o2 Using the Linker. 

The Linker is started by pressing "L" in response to the Workshop command 
prompt. The Linker prompts you for the input files* the listing file and the 
output file. Options may be entered as a response to the input file prompt. 
After all file names and options are entered* the link begins. This means that 
the set of options in effect are the same throughout the link. It is not 
possible to change options part way through the link. When entering an input 
file name* it is not necessary to enter the .OBJ extension, the Linker will 
provide that for all inputs. 

The Linker will accept option commands and input file names from a command 
file. A command file is a text file containing the file names and options* one 
per line. If there is a blank line in the file, the Linker treats this as the 
RETURN that signals the end of the input files. You use a command file by 
typing "<" followed by the name of the text file the commands are in. Create 
the text file by using the Editor. 

The default listing file is the -CONSOLE. You may send the listing to a text 
file by entering its name in response to the listing file prompt. 

After entering the ouput file name, the link begins. If no errors occur during 
the link and all external references are resolved* the output file is 
executable. A message is printed at the end of the link to tell you if the 
output is executable. 

7.3 The Linker Options. 

Linker options can be entered at any time in response to the prompt for an 
input file name. The order in which options are entered is unimportant* 
because they have no effect until the link begins. The last value entered for 
an option is the value used when the link is performed. 

Options are represented by a single character. A "+" in front of the 
character makes that option take effect. A"-" sets the Linker so that option 
will not happen. In addition to being set on or off, some options have 
additional parameters. Numeric parameters can be in either decimal or 
hexadecimal. Hexadecimal numbers are indicated with a leading "$". The 
current setting of all options can be displayed by entering a "?" in response 
to the request for an input file. 

The Linker options are as follows: 
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+A Alphabe-tical listing o-f symbols. The de-fauli is -A. 

+D Debug information. The default is-D. 

+H num +H sets the maximum amount of heap space the Operating 
System can give a program before terminating it. Here^ as in 
the other options* 'num' can be either decimal or hexadecimal. 

-Hnum -H sets the minimum amount of heap space needed by a program. 

+1 Copy interface information into intrinsic library files. The 

default is -I. 

+L Location ordered listing of symbols. The default is -L. The 

location is the segment name plus offset. 

+M fromName toName 

+M maps all occurrences of the segment 'fromName' to the 

segment 'toName'. This allows you to map several small 
segments into a single larger segment. You can thereby 

postpone the segmentation decision until link time by using 
many segment names in the source code. 

NOTE 

Because options have an effect only when the link begins* it is not 
possible to map a segment name to several different names using this 
option. 



+P Production link. The default is -P. +P produces a 'production' 

,OBJ file. A production object file does not contain 
information used by the debugger and the Linker, and intrinsic 
unit files do not contain a jump table. The production object 
file can be executed, but cannot be handled by the Linker or the 
debugger. 

+S num +S sets the starting dynamic stacksize to 'num'. The default is 

10000. 

+T num +T sets the maximum allowed location of the top of the stack to 
'num'. The default is i28K. 

+ W + W tells the Linker to get intrinsic unit information from a file 

other than INTRINSIC.LIB. 

? Prints the options available and their current values. 

7.4 How do I Link a Main Program? 

A main program consists of a Pascal program linked with ail routines 
necessary for it to run. A main program is the only type of executable abject 
file produced by the Linker. To link a main program you must have the 
following: 

A compiled pascal PROGRAM object file. 



Alpha draft 7^5 29 January 1983 



WorkshoD User's Guide -for the Lisa The Linker 



• Object files for all the units the program uses. This includes files for 
regular units and assembly lanquage routines. Any intrinsic units used 
must be defined in INTRINSIC.LIB. 

• lOSPASLIB. 

When you have all the above filesi proceed as follows: 

i. Execute the Linker by pressing "L" when the Workshop command prompt 
is displayed. The Linker will display a header and ask you for an input 
file. 

2. Enter any desired options. See section 7.3 in this chapter for more 
information. Press RETURN after each option entered. 

3. Enter the file names for all the object files* pressing RETURN after 
each one. The file names can be entered in any order. Do not enter the 
.OBJ extension, the Linker automatically appends it. 

4. Press RETURN to indicate the end of the input files. 

5. The Linker prompts you for a listing file. Enter the file name desiredt 
or press RETURN to accept the de-Fault of displaying the listing on the 
-CONSOLE. 

6. The Linker prompts you for the output file. Enter the name of the 
executable file you want produced. Do not enter the .OBJ extension, 
that will be supplied automatically. 

The linking process begins when you press RETURN after entering the output 
file name. If the link is successful, the message "Output is executable" v^ill 
be displayed. If the link is not successful, error messages will be displayed. 

7.5 Regular and Intrinsic Units. 

The two types of units are regular units and intrinsic units. Both of them are 
separatly compiled code modules that may be used by a main program or 
another unit. 

The syntax of a Pascal unit is explained in the Pascal Reference Manual for 
the Lisa . 

A regular unit is combined with a main program by the Linker and included in 
the resulting object file. An intrinsic unit, on the other hand* is stored 
separately on the disk, and loaded at run time. Thus only one copy of an 
intrinsic unit is kept on the disk, no mater how many main programs use 
routines in it. In addition to being shared on the disk, an intrinsic unit is also 
shared in memory. 

NOTE 

In the current implementation, there is no provision for creating 
intrinsic units. Only intrinsic units supplied by Apple can be used. 



7.5.1 How do I use a Regular Unit? 
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A regular unit is a separaieiy compiled segment o-f code. It is written in 
Pascals compiled^ and code generated. See the Pascal Reference Manual -for 
the Lisa for information on how to write a unit. See Chapter 5 in this manual 
for information on compiling the unit. 

After you have created a unit* the routines in it may be accessed from any 
other program or regular unit you write. The Linker is used to combine a main 
program with all units it uses. The result is an executable object file 
containing all the needed routines. 

To use regular units with a main program* follow the procedure in section 7.4. 
As input* you must give the Linker: 

• The object file of the main program. 

• The object files of all units used by the main program. 

• The object files of ail units used by other units. 

• lOSPASLIB. 

The Linker will combine all these object files into an executable object file. 
It will also do a "dead code analysis" to eliminate any routines that are not 
used* thus preventing the object file from becoming any larger than is 
necessary. 

When regular units are used by more than one main program* a separate copy 
of each routine used is stored in each executable object file. This "waste" of 
disk space and memory can be prevented by using intrinsic units instead. 

7.6 The Linker Listing. 

A listing is produced each time a program is linked. This listing can be sent to 
a file* or displayed on the console (the default). The +A option will give you 
an alphabetical list of the symbols (procedure names) used in the link. The +L 
option gives you a list of the names in order of their location. The listing is 
produced in stages* as follows: 

i. The input files are read* and a summary of the resources used is printed. 

2. The linking process begins. Information about the size of each segment 
is printed. 

3. Errors are reported* and you are told if the output is executable or not. 

If you requested optional listingst they will also be printed. An example of a 
Linker listing with no options requested is shown in Figure 7-i. 

] inker] isting 
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Figure 7-1. A Linker Listing. 

7.7 Resolving External Names. 

An external name is a symbolic entry point into an object module. All such 
names are visible at all times-- there is no notion o-f the nesting level o-f an 
external name. External names can be either global or local. A local name 
begins with a $ followed by 1 to 7 digits. No other characters are allowed. A 
global name is any name which is not a local name. 

The scope of a global name is the entire program being linked. Unsatisfied 
references to global names are allowed. Only one definition of a given global 
name may occur in a given link. (The one exception to this is that the Linker 
will accept duplicate names where one instance is in a main program or 
regular unit> and the other is in an intrinsic library file. In this case> a 
warning is issued* and the entry in the main program or regular unit is used.) 

The scope of the local name is limited to the file in which it resides. When a 
link is done> global names are passed through to the output file unmodified, 
but local names are renamed so that no conflicts occur between local names 
defined in different files. All references to a given local name must occur 
within the same input file. 

7.8 Module Inclusion. 

There are two different cases of what modules the Linker includes in the 
output file. When linking an intrinsic unitf all code modules in the unit are 
included. When linking a main program with regular units* the Linker does a 
dead code analysis and does not include any modules that are not used. 

7.9 Segmentation. 

Segmenting a program makes it possible for portions of the program that are 
not being used to be swapped out to disk* thus making better use of memory. 
The way a program is segmented will have important effects on its 
performance. 

Segmentation is controlled by two things: 

• The $S Compiler command* that assigns segment names to source code 
modules. 

# The +M Linker option, that allows you to remap compiler segment names 
into new segment names. 

The usual strategy for segmenting a program is to use the $S compiler 
command to divide the code into many small segments* then to map these 
segments into a few larger physical segments with the +M Linker option. 
This will allow you to change the segmentation of the program by ^st 
relinking it. The segmentation can then easily be adjusted to produce the 
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best swapping characteristics. 

Assembly language routines are by de-fault placed in the blank segment. You 
can use the .SEG directive to specify another segments or change the 
segment with the ChangeSeg utility. See the Chapters 6 and 18 for more 
information. 

7.19 Error Messages. 

The Linker produces three different types of error messages* depending on 
the severity of the error it encountered. 

The firstj and least severe type of message* is called a warning. A warning 
message is given when the Linker detects a condition that is potentially 
dangerous* but not definitly an error. A warning message always begins with*. 

*** Warning 

If the warning message occurs while entering a command or file name* you 
may simply reenter the command correctly* and the Linker will proceed as 
though nothing had happened. 

The second type of message is called an error. An error means that the 
Linker has discovered a condition that makes it impossible to complete the 
link successfully. The link process is continued* so that any further errors 
can be discovered. An error message begins*. 

*** Error 

A fatal error is a condition that makes it impossible for the Linker to 
continue the link. The link is terminated immediatly* and a message is 
displayed beginning: 

*** Fatal Error 

A complete list of all Linker messages is given in Appendix A. 
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Clna.p±erS 
THE OE BUQGE R 

8.1 The Debugger 8-2 

The Debugger allows you to examine and modi-fy memory t set breakpointst 
assemble and disassemble instructions, and other -funciions for run-time 
debugging. 

8.2 Using the Debugger 8-2 

Enter the debugger by pressing D in response to the command prompt^ or by 
pressing the NMI key. The debugger prompt (» indicates that it is ready to 
accept commands. 

8.3 The Debugger Commands ........................................... 8-3 

Commands are available -for assembly and disassembly of instructions, 
displaying memory and registers, setting breakpoints and traces, memory 
management, and base conversions. 

8.4 Summary of Debugger Commands 8-10 
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"thie: debugger 

8.1 The Debugger. 

The Debugger allows you -to examine and modi-fy memoryj set breakpoints* 
- assemble and disassemble instructions* and perform other functions for 
run-time debugging. 

Procedure names are available to the debugger for program units compiled 
with the D option on. The debugger uses the symbolic names wherever 
appropriate. 

The debugger's symbol table combines the user symbol table and the 
distributed procedure names. The user symbol table contains symbols the 
user defines while using the debugger and the predefined symbols for 
registers. Each entry contains twelve bytes. The first eight bytes are the 
symbol name, and the last four bytes are the symbol's value. Section 6.4 in 
this manual contains more information about the run-time environment of 
programs. 

8.2 Using the Debugger. 

Type D to the command prompt to invoke the debugger. It asks: 

Debug what OS file? 

Enter the name of the object file you want to debug. It will be Run with a 
breakpoint at the first instruction that will drop you into the debugger 
immediately. The debugger command prompt is '>'. The default radix is 
hexadecimal. 

Another way of getting into the debugger is by pressing the NMI (non 
maskable interrupt) key which is the "-" key in the top row of the numeric 
keypad. 

When you get the command prompt, the debugger is ready to accept commands 
that allow you to: 

• Display and set memory locations 

• Set and display registers 

• Assemble and disassemble instructions 

• Set breakpoints, patchpoints, and traces 

• Manipulate the memory management hardware 

• Set up timing buckets for execution timing 

• Perform utility functions including: 

• symbol and base conversion 

• move the debugger window 

8.2. i Examples of Using the Debugger. 

This section gives examples of how to use the debugger. An explanation of all 
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debugger commands is given below in Section 8.3. A summary of all debugger 
commands is given in Section 8.4. 

If you type a file name to the prompt from the Debug commands the debugger 
starts up with the program counter at the start of the program. To see one 
instruction disassembled (say at 32F96), type 

HD32F96 

ID stands for Immediate Disassemble. Sach subsequent ID command* if given 
without any address^ disassembles the next instruction found. In addition to 
printing the value of each byte> the debugger prints the ASCII equivalent of 
that value* if a printable one exists. If none exists* it prints a period. 

To disassemble 26 consecutive addresses* type 

>IL 

IL (Immediate Disassemble Lines) can also be followed by an address. 
Subsequent IL commands disassemble successive blocks of 26 consecutive 
locations in memory. 

If the object file being examined was compiled with the D+ compiler option* 
the procedure names are available in the debugger and can be used in any 
expressions. For example* 

>IL Foo 5 
disassembles the first 5 lines of procedure 'Foo'. 

>BR Foo+46 
sets a break point 46 bytes into procedure 'Foo'. 
You can also use labels in immediate assemblies: 

>sy Ken 6666 

>A Ken NOP 
assembles a NOP instruction at the address 'Ken'* which in this case is 6666. 

>A 6666 

>Rich: JMP $166 

><RETURN> 

enters the immediate assembler at 6666, defines the label 'Rich'* and 
assembles a JMP instruction. 

8.3 The Debugger Commands. 

This section gives the definition of each debugger command. The commands 
are grouped together according to function. 

8.3.1 Definitions. 

Constant A constant in the default base. 

SConstant A hex constant. 

^Constant A decimal constant. 
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'ASCII String' 
Name 



Expr 



Exprlist 
Register 



RegName 



An ASCII string. 
A symbol in the symbol table. 

An expression. Expressions can contain namest regnamest 
stringst and constants. Legal operators are + - * /. 
Expressions are evaluated left to right. * and / take 
precedence over + and -. ( and ) can be used to indicate 
indirection. < and > can be used to nest expressions. In 
those cases where an odd value is probably a mistake, the 
debugger warns you that you are trying to use an odd 
address. If you decide to go ahead, it subtracts one from 
the address given. If the compiler option D+ is used, 
procedure names are legal in expressions. 
A list of expressions separated by blanks. 
The name for any of the 68000 registers, as follows: 
D0..D7 are the data registers, A0..A7 are the address 
registers, the program counter PC, the status registers 
SR, US, or SS. Note that A7 isSP (the stack pointer). 
RD0..RD7, RA0.,RA7, PC, US, or SS. A predefined symbol 
in the symbol table with a value set by the debugger. The 
value is equal to the value of the register in question. The 
debugger automatically updates the values of these 
symbols. The 'R' is appended to distinguish the register 
names from hexadecimal numbers. 
8.3.2 Display and set memory locations. 

The following commands are used to display and set memory locations. 

SM expri exprlist 

Set memory with exprlist starting at expri. SM assumes that each element of 
exprlist is 32 bits long. To load different length quantities, use SB or SW 
described below. If the expression given is longer than 32 bits, SM takes just 
the upper 32. For example, if we ask the debugger to*. 

SM 1000 'ABCDE' 

it deposits the ASCII equivalent of 'ABCD' starting at 1000. 

SB expri exprlist 

Set memory in bytes with exprlist starting at expri 

SW expri exprlist 

Set memory in words with exprlist starting at expri 

SL expri exprlist 

Set memory in long words with exprlist starting at expri. For example, 

SL 100 i 
is equivalent to 

SM 100 0000 0001 

DM expr 

Display memory. Display 16 bytes of memory starting at expr. DM RA3+10, 
for example, displays the contents of memory from 10 bytes beyond the 
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address pointed to by A3. DM (110) displays the contents of the memory 
location addressed by the contents o-f location 110. 

DM expri expr2 

Display memory. H expri < expr2> then display memory -from expri to expr2. 
Otherwise^ display memory -for expr2 bytes starting at expri. 

DB expr 

Display memory as bytes. 

DW expr 

Display memor-y as words. 

DL expr 

Display memory as long words. 

FB 5tarting_addr count data 

Find Byte. Find the byte or bytes 'data' in memory between 'starting_addr' 

and 'starting_Addr'+'count'. 

FM starting^addr count data 

Find Memory. 

FW starting_addr count data 

Find Word. 

FL starting_addr count data 
Find Long word. 

8.3.3 Set and display registers. 
TD 

Display the Trace Display at the current PC. An example o-f the trace display 
is shown in Figure 8-1. It shows the instruction executing at the time the 
program was interrupted^ the current value o-f all the registers* and the 
current domain and process. 

traced! splay 



{r 



Y-^^ 



u 



Figure 8-i. The Trace Display. 

register 

Display the current value of the register. D0» for example^ is a command to 
the debugger to display the current value in the register D0. RD0j on the 
other handf is a name automatically placed in the symbol table to give you a 
handle on the contents of D0 in an expression. Thust to display the current 
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value in the DO data register^ type the command DO. To display the 
instruction pointed to by the A0 address register^ type the command ID RA0 
(Immediate dissassemble at the address RA0t which is predefined to be the 
contents of the A0 register) 

register expr 

Set the register to expr. For ex ampler to set register D3 to zero* type D3 0. 

8.3.4 Assemble and disassemble instructions. 

These commands are used to display code in assembly language format* and to 
enter code in the form of assembly language statements. 

A expr statement 

Assemble one or more assembly language statements (instructions) starting 
at expr. You can continue assembling instructions into consecutive 
locations, pressing RETURN after each statement. Type Mt RETURN to 
exit the immediate assembler. Note that the immediate assembler cannot 
assemble any intrinsic unit instructions* but they will be correctly 
disassembled. Code segments may be write-protected* which will prevent 
you from assembling instructions into them. This can be overridden with the 
WP command to disable write protection. 

A expr 

If you use the form A expr, the debugger prompts you for the statement to be 

assembled. 

ID 

Disassemble one line at the next address 

ID expr 

Disassemble one line at expr 

IL 

Disassemble 20 lines at the next address 

IL expr 

Disassemble 20 lines starting at expr 

IL expri expr2 

Disassemble expr2 lines starting at expri 

IX statement 

Immediate execution of a single instruction. The users PC is not changed by 
this operation. 

8.3.5 Set breakpoints and traces. 

These commands are used to trace program execution. 

BR 

Display the breakpoints currently set. You can set up to 16 breakpoints with 
the debugger. Break points are displayed both as addresses and as symbols. 
An asterisk marks the point of the breakpoint in the disassembly. 

BR exprlist 

Set each breakpoint in exprlist. Symbols are legal, of course, so we can: 
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BR Raiph+4 
i'f Ralph is a known symbol. 
Expressions can be o-f the form: 

ppraaaaa 

where pp is the process numberr and aaaaa is the address in that process 
where you want the breakpoint set. If the process number is 0^ the breakpoint 
is set in system code in domain 0. If no process isgiven^ the current process is 
assumed. The current process is shown in the TD display described above. 

Breakpoints cannot be set on intrinsic unit instructions. 

CL 

Clear all breakpoints 

CL exprlist 

Clear each breakpoint in exprlist 

G 

Start running at the current PC 

G expr 

Starting running at expr 

T 

Trace one instruction at the current PC 

T expr 

Trace one instruction at expr 

SC expr 

Stack Crawl. Display the user call chain. Expr sets the depth of the display. 
It can be omitted. 

RB 

Reboot. This command should not be used while you are in the Workshop. The 

Lisa is reset. 

procedure name 

This calls a user procedure or function. It is the users responsibility to save 
and restore registers and push any necessary parameters. If you want 
execution to stop upon return, you must set a breakpoint on the current PC. 
For example: 

BR PC ; set break point on PC. 

IX MOVEM.L De-A6,-<A7) ; save registers. 

; push params if needed* 

FOO ; call procedure FOO. 

IX MOVEM.L (A7)+,D0-A6 ; restore registers. 

CL PC ; remove break point. 

A function can be called in a similar manner. Remember to allocate space for 
the function result before pushing any parameters. Use either CLR.W -(A7) 
roCLR.L -(A7). 
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A procedure iha-t may need to be called is OSQUIT. H exits -from the OS. We 
reccomended that you avoid this whenever possible. 

8.3.6 Manipulate the Memory Management Hardware. 

These commands change the memory management hardware of the Lisa. More 
information on the memory managment hardware can be found in the Lisa 
hardware manual. CHECK NAME. 

LP expr 

Convert logical address to physical address. 

DO expr 

Set the SEG1/SEG2 bits. These bits determine the hardware domain number. 
If the Status Register shows that you are in supervisor state > then the 
effective domain is zero, and the domain number returned by the debugger is 
the domain that would be active if the SR were changed to user state. 

WP 0or i 

Diable (9) or Enable (1) Write Protection. The default is 1. 

MM start Cend_jDr_count3 

MM with one or two arguments displays information about the MMU 
registers. The second argument defaults to 1. If the starting address is 
greater than the second argument, the second argument is a count of the 
number of MMU registers to be displayed. If the starting address is less than 
the second argument, the second argument is the last register displayed. 

MM 70 

displays 

SegmentC703 OriginC0003 LimitC003 ControlCCD 

These values are the Segment Origin, Limit, and Control bits stored by the 
hardware for each MMU register. As can be seen from a careful perusal of 
the hardware documentation, a Control value of C means the segment in 
question is unused (invalid). If the Control value is valid (7, for example), the 
debugger also displays the Physical Start and Stop addresses of the segment. 

MM 4100 8 

displays the MMU register information for the S registers starting at 
register 64 (decimal 100). 

MM num org lim cntrl Cend_or_count3 

The MM command followed by four arguments sets the MMU information for 

segment 'num'. The Origin, Limit, and control bits can be changed. 

MM 70 100 ff 7 

sets the Origin of segment 70 to 100 and the control bits to 7 (a regular 
segment). The segment limit of -1 makes the segment 512 bytes long. 

8.3.7 Timing Functions. 

The debugger allows you to create up to 10 timing buckets for measuring 
execution times. Using the microsecond timer in Drivers, time is 
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accumulated in each bucket and saved along with a count of the number of 
times the bucket was entered. 

Typically f this would be done as follows: 

!• Enter the debugger for a given process and create one or more timing 
buckets with the TB command. 

2. Set a break point to stop execution at some point. 

3. Go. 

4. When the breakpoint is reached* print the timing summary with the PT 
command. 

5. Use the End Timing (ET) command to remove all timing buckets. 
The timing commands are as follows: 

BT expr 

Begin timing. Expr specifies the process number. If the BT command is not 
given> the current process is assumed. A process number of can be used to 
indicate domain 0. 

TB addri addr2 

A timing bucket is created from addrl to addr2. 

PT 

Print timing summary. There are five columns printed; 

1. Bucket number 

2. Total time in this bucket. 

3. Number of times this bucket was entered. 

4. Starting address for this bucket. 

5. Ending address for this bucket. 

ET 

End timing. This command prints the timing summary and removes all the 

timing buckets. 

KB e>i^ 

Kill Bucket. This can be used to remove a single bucket. Expr is the number 

of the bucket to remove. 

RT 

Reset timers. This resets the timing and count tables while leaving the 

bucket definitions intact. 

Note that all addresses are in the same process. The process number is 

defined by either the BT command or the first TBt PT? KB? or RT commands If 

the process number is not given in the BT command the current process is 
assumed. 

8.3.8 Utility functions. 
including: 

o symbol and base conversion 
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o moving the debugger window 
o Setting the NMI key 

8.3.8.1 Symbols and Base Conversion 
SY 

Display the values o-f all symbols 

SY name 

Display the value o-f the symbol name 

SY name expr 

Assign Qxpr to the symbol name 

CV exprlist 

Display the value o-f each expression in hex and decimal. 

SH 

Set the de-fault radix to hex 

SD 

Set the de-fault radix to decimal 

8.3.8.2 Moving the Debugger Window: 
P expr 

Set port number to expr. Valid port numbers are: 

Lisa Keyboard- and screen (de-fault) 

1 UART Port A (farthest from Power Supply) 

2 UART Port B 

If you move the port to a UARTt you must have a modem eliminator connected 
to that port. 

RS 

Display the patch Return address Stack 

8.3.8.3 Setting the NMI key: 
NM 

Displays the key code for the NMI key. 

NM expr 

Sets the NMI key to be key code expr. A value of zero disables the NMI key. 

For example: 

>NM $21 

Sets the NMI key to be hex 21* which is the "-"key in the top row of the 
numeric keypad. 

8.4 Summary of the Debugger Commands. 

procedure name Call the procedure. 

register Display the current value of the register. 

register expr Set the register to expr' 

A eyipr- statement 
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A expr 

BR 

BR exprlist 

BT e>ipr 

CL 

CL exprlist 

CV exprlist 

DB expr 

DL expr 

DM exprl eKpr2 

DO expr 

DR 

DW expr 

ET 



FB starting_addr 

FL starting^addr 

FM 5tari:ing_addr 

FW s"tar"tinQ_addr 

G 

G expr 

ID 

ID expr 

IL 

IL expr 

IL exprl expr2 

IX sia-tement 

KB expr 

LP expr 

MM expri expr2 

MM num org lim ctrl 

MR 

NM 

NM expr 

P expr 

PT 

RB 

RS 

RT 

SB expr 1 exprlist 

SC expr 

SD 

SH 

SL expri exprlist 



count data 
count data 
count data 
count data 



Assemble one statement (instruction) at 

expr. 

Display the breakpoints currently set. 

Set each breakpoint in exprlist. 

Begin timing process expt" 

Clear all breakpoints 

Clear each breakpoint in exprlist 

Display the value of each expression in hex 

and decimal. 

Display memory as bytes. 

Display memory as long words. 

Display memory. 

Set the SEGi/SEG2 bits. 

Display index or ranges of dump RAM. 

Display memory as words. 

End Timing - print summary and remove 

buckets 

Find Byte. 

Find Long 

Find Memory 

Find Word 

Start running at the current PC 

Starting running at expr 

Disassemble one line at the next address 

Disassemble one line at expr 

Disassemble 29 lines at the next address 

Disassemble 20 lines starting at expr 

Disassemble expr2 lines starting at expri 

Immediate execution of one instruction 

Kill Bucket expr 

Convert logical address to physical address. 

Display MMU information 

Set MMU information 

Set a value level #5 interrupt on a word 

change. 

Displays the key code of the NMI key 

Sets NMI key code to expr 

Set port number to expr. 

Print timing summary 

Reboot. 

Display the patch Return address Stack 

Reset timers 

Set memory in bytes with exprlist starting at 

expri 

Stack Crawl. 

Set the default radix to decimal 

Set the default radix to -hex 

Set memory in long words with exprlist 

starting at expri. 
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SM expri exprlist Set memory with exprlist starting at expri. 

SW exprl expriist Set memory • in words with expriist starting at 

expri 

SY Display the values of all symbols 

SY name Display the value o-f the symbol name 

SY name expr Assign expr to the symbol name 

T Trace one instruction at the current PC 

T expr Trace one instruction at expr 

TB addrl addr2 Create Timing Bucket -from addrl to addr2 

TD Display the Trace Display at the current PC 

WP e or 1 Diable (0) or Enable (i) Write Protection. 
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ChsLpter 9 
USING EXEC F"IL.ES 

9.1 Exec Files............... .....9-3 

Exec -filesare scenariosof commands to be automatically performed by the 
Workshop system. They can use parameters, and conditional execution. 

9.2 Exec File Statements ................................................... 9-3 

Exec file statements are of two types: normal lines^thatcontain Workshop 
commands* and exec command lines^ that tell how toprocessthe exec file. 
Exec command lines include lines to: set parameter values* perform input 
and output* and to control conditional execution. 

9.3 Using Exec Files .......................................................9-10 

Exec filesare invoked using the Workshop Run command. Thisinvokation 
line can set the values of parameters* as well as select exec options. 

9.4 Example Exec Files....... .........9-14 

Thissectioncontains examples of exec files. 

9.5 Exec File Programming Tips ............9-18 

Thissectioncontains tipson how to write exec tiles. 

9.6 Exec File Errors........ ...........................................9-13 
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Using Execz F"ile-s 

9.1 Exec Files 

Exec -files are scenarios o-f commands to the workshop system. They are 
contained in a text filef created with the Editor^and are executed with the 
Run command. They consist of the actual characters you would type to the 
Workshop toper-form the function you wantjinterspersedwithspecialexec 
file commands that allow you to use parameters and conditions to vary 
some portionsof the scenario. 

In its simplest f orm^ an exec file contains the characters you would pressto 
perform the desired operation. Forexample* to compile a Pascal program^ 
the exec file would contain: 

Pmyprog 

The P invokes the Pascal compiler* myprog is the name of the source file. 
This could be followed by further lines to Generate > Link^ and Run the 
program. 

Special exec file commands allow you to use parameters and conditionally 
perform the Workshop commands. This would allow you to setup an exec 
file to compile? Generate j and optionally Link any Pascal program. Such an 
exec file isshown in Figure9-i 

$EXEC 

$ < Th i 5 exec f j 1 e comp i 1 es and Generates a Pascal program. } 
$ { If the second parameter i s L <or 1 > the program i s Linked ) 
$IF%0= •'■ "■ THEM {no parameter entered) 

$yRITE 'Compile what f ile?^ 

$READLN /:0 
$ENDIF 
P%0 

{ no 1 i st ing f i 1 e) 
{ def aul t I-code file } 
G%0 

•Cdef aul t object file) 
$IP UPPERCASE':'<1) = -'L-' THEr>l 

L '<0 

lOSPASLIB 

{ end of 1 i nker i npu t ) 

{ no 1 ist f i le } 

%0{ output f i 1 e name } 
$ENDIF 
•$ENDEXEC 

Figure 9-1. Example Exec File 

9.2 Exec File Statements 

Exec file statements are contained on one line. There are two typesof exec 
file linest exec command lines? and normal lines. Mormal lines contain 



Alpha draft 9-3 7 February 1933 



Workshop Re-ference Manual -for the Lisa Using Exec Files 

commands ±o be processed by the Workshop system. Exec command lines 
handle the other -featuresof exec -filestsuch as parameters and conditional 
statements. 

You may use up to 10 parameters in an exec -filetnumbered as %0 through 
%9. These receive their values -from the invocation o-f the exec -file^orthey 
are assigned values during the exec file execution. When a parameter- 
appears in a normal line, it is replaced by the string value o-F that 
parameter. These parameters can be used both as inputs to the exec tile 
and as temporary variabieswithinit. 

Exec command lines startwith a $; they control the operation of the restot 
the exec file. Exec command linesare free format, as long as the orderof 
thier elements is preserved. Any number of blanks can occur before any 
element of a command line. 

Normal command linescontain commands forthe Workshop system. These 
lines are sentto the Workshop exactly asthey appear. Any extra blanks will 
be sent to the Workshop and will be treated exactly as if you had typed in 
those blanks. 

Comments are delimited by curly braces (Cand ». They can appear in either 
a normal or an exec command line. Comments are complsteiy removed 
from normal lines. 

The tilde {"") isusedasa literalizing character in normal lines. Itpassesthe 
following character through without processing it. This allows you to pass 
$, %,and { to the Workshop system without having them be interpretedasan 
exec commandr a parameter, or a comment. Tilde can be passed as'""""' 

The following is a descriptionof each exec command line type. 

9.2.1 Beginning and Ending Exec Files 

The general form of exec filesisthey must begin with a "$EXEC" line and 
must end with a "$ENDEXEC" line. The exceptions to this basic rule (for 
those miscreants who embed their exec filesin their program sources)are: 
(1) one line of textmay preceed the "$EXEC" line if the "I" invocation option 
is used, and (2) any amount of textmay follow the "$ENDEXEC" line,butit 
will be ignored. 

9.2.2 Setting Parameter Values 

You can setparameter values in an exec file by using the SET and DEFAULT 
operations. The REQ.UEST operation prompts the user for the value of a 
parameter. 

SETand DEFAULT 

The SET and DEFAULT commands provide a way of changing the value of a 
parameter inside of an exec file. The form of thesecommands is;. 

$ SET <%n> TO <strexpr> 

and 

$ DEFAULT <%n> TO <strexpr> 
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where <%n>isa parameter reference and -(strexpr)' is a string ex pressionas 
described in the following section. 

The effect of the SET command is to change the value of the specified 
parameter to the value of the given string expres.sion. The effect of the 
DEFAULT command is similar to that of the SETcommand, however^the 
assignment only taKes place if the value of the specified parameter is the 
null string when the DEFAULT command is encountered. Thust this 
command can be used to supply default values to parameters that have 
been leftunspecified or empty in the exec invocation line. 

REQUEST 

The REQUEST command provides a way to prompt for values from the 
console. Itsform is: 

$ REQUEST <%n> WITH <5trexpr> 

The REO.UEST command will print the given string expression to the 
console and will read a line from the console which it will assign to the 
specified parameter. Thus the <str Q>ipr> is the prompt that you will 
requestwith. 

9.2.3 Input and Output 

Input to an exec file isrequestedby the READLN of READCH command. 
The WRITE andWRITELN commands allow you to output values. 

READLN and READCH 

TheREADLM and READCH commands ailovv^execfilesto read in text from 
the console and to assignit to a parameter variable. This mechanism may 
be used to obtain parameter values^ to obtain values to control conditional 
selection? to pause until the user indicates to continue » or for any other 
purpose. The form of thesecommands is: 

$ RSADLM <%n> 

and 

$ READCH <%n> 

READLN will read a line from the console and will assignit to the specified 
parameter. READCH will read a single character from the console (if 
<return>istypedthatcharacter willbe a blanK). 

WRITE and WRITELN 

The WRITE and WRITELN commands allow exec files to write text to the 
console screen. This text may be used forinformatory messageSfpromptst 
orfor any other purpose. The form of thesecommands is: 

$ VJRITE C <strexpr> C , <5trexpr> 3* 1 

and 

$ WRITELN C <strexpr> C , <:strexpr> 1^ 1 
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That ist these commands take an arbitrary number of string expressions^ 
separated by commas? as arguments. The stringsarewrittento the current 
console line* and in the case o-f WRITELN a -Final carriage returnis written. 

9.2.4 Conditional statements 

Conditional statements allow you to perform certain commands depending 
on the conditions at the time the exec file is run. These conditions can be 
based on the value of parameters and on the f ilesavailable to process. The 
condition is stated in the form of a boolean expression^and can include 
built in boolean functions to determine thecondition of files. 

ThelFStatement 

The IFjELSEIFtELSE and ENDIF commands allow conditional selection in 
exec files. The syntax of these commands is as follows: 

$ IF <boolexpr> THEN 
< stuff > 
C$ ELSEIF <boole>ipr> THEN 

<5tuff> ]* 
C$ ELSE 
•(stuff > ] 
$ ENDIF 

where <bool expr-y is a boolean expression as described in the following 
section and <stuff> is made up of arbitrary normal and command lines 
(other than commands that would be a part of the current IFconstruct). The 
"C...3-*"constructabove indicates that zero or more ELSEIFcommands may 
appear between the IF and the ENDIF command* while the "C...]"indicates 
thatzero or one ELSE command may appear justbef ore the ENDIF. 

The IF construct is evaluated in the usual Vv'ay. First* the boolean 
expression on the IF command itself is evaluated; if it is true then the 
<stuff>betweentheIFand the next ELSE IF (if any) or ELSE (if any) or ENDIF 
is selected; otherwise it is not selected. All remaining parts of the IF 
construct up to the ENDIF will be parsed but will not be selected once one 
of the <bool expr>sistrue and itscorresponding (stuff >is selected. To say 
that (stuff >is selected means that any normal lines will generate textand 
that any command lines will be processed. Conversely* to say that<stuff> 
is not selected means that any normal lines will not generate textand that 
command lines will be parsed (for correctness) but not executed. If the 
<bool expr> on the IF is not true then the following ELSEIFor ELSE will be 
processed. If an ELSEIFis next* its <bool expr> will be evaluated* and* if 
true* its following (stuff)- will be selected and the remainder of the IF 
construct will not be selected. Processing of the IF construct continues 
until one of the <bool expr>son an IForELSEIFistrue or until the ENDIFis 
reached. If no <bool expr> is true before the ELSE (if any) is reached* its 
<stuff>wiilbe selected- 

IFconstructsmay be nested within each otherto an arbitrary level. 
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BooleanExpressions — comparison and logical operators 

BooleanseKpressions«bool e>{pr>s) enable you to testo-f string values and 
check properties of files. The grammar for boolean expressions is as 
follows: 



<bool expr> 

< binary logic op> 



<boolterm> C<binary logic Dp> <boolBxpr> D* 

AMD 
I OR 



<booltepm> 



<booHactor> 



<bool factor > 

1 ( <boolexpr> ) 

I NOT ( <boolexpr> ) 

<strexpr> <strop> <strexpr> 
I < bool function > 



< strop)- ::= = 

The basic element of a boolean expression (a <bool factor";) is either a 
boolean function (see the next section) or a string comparison, testing for 
equality or inequality. These basic elements may be combined using the 
logical operatorsAND>OR and NOT^withparenthesesusedforgrouping. All 
these operatorsf unction in the usual way. 

Boolean Functions— EXISTS and NEWER 

Several functions returning boolean results are provided for use with the 
conditional contructs. 

The EXISTS function allows you to determine whether a file or volume 
exists. The function has the following form: 

EXISTS ( <strexpr> ) 

where <str expr> is a string expression whose value is the name of a file. 
Typically this <str expr> will be an expanded string constant (discussed 
above), such a5"%i.obj". 

The NEWER function allows you to determine whether one file is newer 
than another file* that is, whether its last-modified date is more recent 
than the last-modi-fied date of anther file. The function has the following 
syntax: 

NEWER (<strexpri>,<strexpr2>) 

where the <strexpr>s specify filenames. TRUE willbe returned if the first 
file is newer than the second. A preprocessor run-time error will occur if 
one of the f ilesdoes not exist. 
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9.2.5 String Expressions 

A string BKpres5ion«strexpr» may speci-fya stringby a number o-f means, 
as noted in the -Following grammar. 

<streKpr> ::= -(parameter reference)- 

I •< str const ant > 
I -(expanded strconstant)- 
I -(str-function)- 
I -(exec -function call> 

A parameter re-ference has the usual "%n'V-form. A stringconstant has the 
standard form of text delimited by single quotes ('), with a quote inside the 
string specified by the double quote rule^ as in That^'sall* folks!'. An 
expanded string constant is similar to a stringconstant^except that double 
quotes (") are used as delimiters and parameter references are expanded 
within the string. A string function is a preprocessorf unction which returns 
a string value (these are described in the following section). An exec 
function call is an invocation of an exec filewhich returnsa string value <as 
described in a followingsection, "Exec Function Calls"). 

String Functions— CONCAT and UPPERCASE 

The string functions CONCAT and UPPERCASE may be applied to other 
stringexpressionstoproduce new stringvalues. 

The CONCAT function allows several string ex pressionsto be combined to 
produce a result which is a single string. The CONCAT function has the 
form: 

CONCAT ( (strexpr)- C , <strexpr> 3« ) 

Thatis^CONCAT takes a listofstringexpressionstseparatedby commas. 

The UPPERCASE function converts any lower case iettersin its argument 
to upper case. It has the following form: 

UPPERCASE ( <strexpr> ) 
An example of the use of thisf unction is 

$ SET%0TOUPPERCASE (%0) 
which will setparameter to an uppercase versionofitspreviousvalue. 

9.2.6 Nesting exec Files 

Exec files can be nested by calling another exec file by using the SUBMIT 
command. The called file can be a function^ which means that it will 
RETURN a value to a parameter in the calling exec file. 

SUBMIT 

The SUBMIT command allows nesting of exec files, that is, it allows 
another exec file to be called from within an exec file. The form of the 
SUBMIT command is: 

$ SUBMIT -(exec command)- 
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Vy'here <exec command> is an exec command of the same form as you would 
have following the "exec/" or "<" at the Workshop shell command level. 
This exec command may include parameters and exec options in the usual 
fashion. 

The effect of the SUBMIT command is to process the specified exec file^ 
putting any generated exec output text into the current exec temporary 
file. Thusjwhile a single exec -File may have sever^.lr.csied sub-exec files^ 
only a single temporary output file is generated which includes the output 
generated by all of the input files. Exec fiiesmay be nested to an arbitrary 
level. 

Within the text of the <exec command)-^ referencesto"%n"parameterswill 
be expanded and the literalizingcharacter ("*""*") will be processed. Be aware 
that this is the only processing that takes place within an exec command. 
Everything up to the first" <" or the end of the line (if no parameter list is 
present) will be taken to be the exec file name. If there is a "(" the 
parameter list will be taken to be everything between this"(" and the next 
)". An <exec command)- may not be splitacrosslines. 



li SI! 



Note that only the "I" (Ignore firstline) and "B" (Blanks significant) options 
are valid on a SUBMIT command, while the "R" (ReRun),"S" (Stepmode) and 
"T" (Temporary file saved) options are only applicable from the main exec 
invocation line. 

$RETURN — Exec Functions 

The RETURN command allows exec files to return string values to other 
(calling) exec files. Thus the RETURN command can turn an exec fileintoa 
function. The form of the RETURN command is: 

$ RETURN C<5trexpr> ] 

Executing a RETURN command will terminate the current exec file and 
return to the calling exec file with the specified string value. The method 
by which exec functions are called isdescribed in the following section. 

Exec functions can be used to do such things as determining whether a 
program file (and itscorresponding include filestif any) have been modified 
since their last compilation* and may thusbe used to conditionally submit 
compiles. If written generally enough » such a function could be used by 
many exec files. 

Exec functions can produce side effects^that is»they may contain normal 
lines which will get placed in the temporary file. While the intentionaluse 
of such side effectsis unlikely, inadvertentinstances may occur and willbe 
potentially hazardous to your exec files. (An unexpected blank line in the 
middle of an exec file can often throw it out of sync.) 

Exec FunctionCalls 

Exec function calls return string values, and are thus are one of the basic 
elements of string expressions. They may also appear in boolean 
expressions, supplying arguments for string comparisons.. (A typical use of 
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an exec -function would be to return a boaiean value by returningeitherthe 
string'T'or 'F'.) The form of an exec function call is: 

< < filenames- C( <arglist> ) ] 

where "<" is the character that signalsa function invocation (Justin the way 
that this character identifiesexec filesfor the Workshop's Run command). 
The <file name> and optional <arg iist> are the same as in the SUBMIT 
command. 

Due to our liberal conventions concerning what characters (including 
blanks) may appear in file names» the preprocessor must make some 
assumptions about how to identify the exec function file name and the 
argument list. Recognizing the file name is more of a. problem in the case 
of exec functions than it for the SUBMIT command* since exec function 
calls may appear inside of arbitrary string expressionst while an exec 
invocation appears by itself in a SUBMIT command. The simple rule the 
preprocessor uses is*, if the exec function invocation has an argument list^ 
the file name is assumed to be everything between the "<" and the "(" 
beginning the argument list; otherwise* the file name is assumed to be 
everything between the "<" and the end of the line, which means that you 
will have to supply an empty argument list to an exec f untion with no 
arguments if the function call is not the lastthing on the command line. 

The processing of the textof a function call isthesame as that of a SUBMIT 
command* that is^the only processing that will take place is expansion of 
"%n" parameters and recognition of the literalizing character ("•'"'"). This 
means* for instance, that the text of a function call may not contain an 
embedded function call. Note also that a function call may not be split 
across lines. 

9.3 Using Exec Files 

An invocation line for the preprocessorhasthe following form: 

(exec command)' <execfile> C (<parameter list)) C<exec options) 31 

The <exec command)- can be either "EXEC/" or "-C The -(exec file)- is the 
name of the exec file you wish to run. A ".TEXT" extension will be assumed 
if one is not specified; however* you may override the mechanism which 
suppliesthe ".TEXT" extensionby ending your -(exec file)- name with a dot; 
e.g.* using "f 00." will cause the preprocessortolook forthefile"foo"rather 
than"foortext". 

The optional -(parameter list) is enclosed in parentheses. The parameter 
list may be empty or it may include up to ten parameters delimited by 
commas. For example* we may have an exec file to run compiles which 
takes volume and source file parameters* which we might invoke with 
"compile(foo*-Vy'ork-)". Parameters may be omitted (leaving them as null 
paramters) by specifying them with the null string* as in "compile(foot)"* 
which omits the volume from our previous example. Alternately* 
parameters may be left unspecified altogether* as in " compile (foo)"* in 
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which case they also get null values. Onereasontorleaving oft parameters 
is that the exec file may have been set up to supply de-fault valuest as is 
described below. 

The <eKec options)- which -follow the closing ")" o-f the parameter list 
consist of single letter commands which will modify the behavior of the 
preprocessor; for example* "S" is used to indicate that you want to step 
through the exec file asitisbeing processed^ conditionally selecting which 
commands will be sent to the Workshop shell. The exec options are 
discussedin detailin the "Exec Invocation Options" sectionbelow. 

The preprocessor's output is a temporary file with a "..TEXT" extension. 
The temporary fileistheprocessedversionof your exec commands^ thatis, 
all preprocessor-oriented commands will have been processed and 
removed* leaving only the WorkShop-related commands. This temporary 
file is passed to the Workshop shell executive when the preprocessor is 
done. The Workshop shell will then run the temporary exec file and delete 
it automatically when completed. 

Note that the preprocessor is not case-sensitive*but it does preserve the 
case of parameters and strings supplied by the user. 

Exec Invocation Qp-tions 

A number of options are available when running the preprocessor. These 
options may be specified when invoking the preprocessor or on SUBMIT 
commands. The optionsare specified by single lettercommands following 
the exec parameter list- (A null parameter listshould be used if you want to 
use optionswithoutparametersjas in "<foo()s".)The optionsare as follows: 

"B" indicates that the preprocessor should not trim blanks on outputlines. 
Normally the preprocessor will trim off leading and trailing blanks on 
the lines thatitoutputsto the temporary file. Thisallows you to indent 
normal lines (lines which are not exec command lines) without 
worrying about generating spurious blanks. Thus the preprocessor 
assumes that leading and trailing blanks areinsignificant(which is the 
case for Workshop commands* but which may not be true for some 
perverse programs you may run via exec files). Thisoption will tell the 
preprocessor not to trim such blanks. The option applies only to the 
exec file being runor SUBMITted,and nottoany nestedexec files. 

•'I" indicates that the first line of the exec file is to be ignored by the 
preprocessor. This option is intended for deviants who like to embed 
their exec files in their program sources* in which case thefirstlineof 
the source should be a "(^" and a "^)" should follow the end of the exec 
file*thus commenting itout of the program source. (Note that" (^" and 
"^)" should be used in preference to "{"and "}" since the latter are used 
as comment characters in the preprocessor.) 

"T" indicates that the temporary file which is created (i.e.* the expanded 
form of the exec file) should not be removed afteritisrun. Onereason 
to use this option is to make it possible to rerun an exec file created 
with the step option (see below) without going through the stepping 



Alpha draft 9-11 7 February 1983 



WorKshop Rs-ference Manual -for the Lisa Using Exec File^ 

prompts a second time by running a previously created expanded exec 
tile. The"R" exec option (described below) is used to run old temporary 
exec -files. Note that the "T" option is not allowed on SUBMIT 
commands. 

"R" indicates that the a exec temporary -file which has been saved with the 
"T" option should be rerun^ bypassing the normal processingby which 
the temporary was created. For example^ "-foo" may be an exec tile 
which generates a complicated system via a large number of nested 
exec -files which take a signi-ficantamount o-f time -for the preprocessor 
to digest. It we know we are going to run "too" repeatedly ^ we may 
want to generate the temporary tile only once but runitseveral times. 
The first time we would invoke the preprocessor with "<fao()t"ta 
indicate that the temporary tile should not be automatically deleted 
after it is run. Subsequently^ we would invoke the preprocessor with 
"<foo()r"to rerun the old temporary tile. Note that the "R" option will 
override any others that may be specified^ and it is not allowed on 
SUBMIT commands. 

"S" indicates that the exec file should be processed in "Step Mode" which 
allows selective skipping of output lines and SUBMITS. If thisoptionis 
usedf the following message will appear when you invoke the 
preprocessor: 

Step Mode : 

— in response to "Include ?" answer: Y, N> A (Abort)t K (Keep rest)for I (Ignore Rest). 

— in response to "Submit ?" answer: Y> Nt S (Step)t A (Abort)KK (Keep Rest)* or I 

(Ignore Rest). 
More details ? CNoD 

It you repond wi th " Y" (yes) to the "More details ?" prompt you will 
get further i nf ormat i on on what each of stepp i ng responses means. 

When you invoke an exec tile with the step option you will be prompted 
when a line has been generated and is about to go into the temporary file. 
The line will be displayed followed by "<= Include ?". A responseof "Y" will 
include the line in the expanded exec file. A respon5eof"N" will cause the 
displayed line to be omitted. A response of "A" will abort out of the exec 
file preprocessor and no exec file will be run. A responseof "K" will keep 
(include) all the remaining lines of the exec file, leaving stepmode* while a 
responseof "I" willignore the remainder of the exec tile. 

When a SUBMIT command is encountered when stepping^the SUBMIT line 
will be displayed followed by "<= Submit ?". A responseof "Y" will perform 
the SUBMIT unconditionally, that is, without stepping through it. A 
responseof "N" will ignore the SUBMIT. A responseof "S" will step through 
the SUBMIT tile, a" response of "A" will abort out of the exec tile 
preprocessor and no exec file will be run. A responseof "K" will keep the 
rest of the exec file, leaving step mode, while a responseof "I" will ignore 
the remainder of the exec file. 
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Moi:e that a reponseot"?" to a "Submit ?" or "Include?" prompt will elicit an 
ejjplanationo-f the accepted responses. 

Following are some examples o-f how to use the preprocessor'sstepping 
facility. 

Stepping may be used to resume execution o-f an exec -file which did not run 
to termination. For examplet if our example "compile" exec file includes 
both a compile and a generate step and if we wish to resume with the 
generate step we could invoke the preprocessor with 
"compile (foOf-work~)s". Then^ in response to the "Include?" prompts for 
lines corresponding to the compile step we would hit"N" to skip the lines. 
Upon reaching the firstline of the generate step we would respond with "K" 
to keep the rest of the file ^ and the generate stepof the exec process would 
be performed. 

The stepping mechanism may be used to run only selected partsof an exec 
file. Say^ for instance* that we have a modular set of exec, files which 
generate a whole system of programs, such as the Workshop development 
system* and that one exec file called "make/all" can generate the whole 
system by SUBMITting exec filesforeach of the component programs. The 
exec filesforeach component program (development system tool) make 
use of other exec files to perform such standard activities as compiling 
(and generating) a Pascal unit or program, performing an assembly* 
installing a library* or manipulating files with the V/orkShop's filer. If we 
are performing a system build and find ourselves constantly having to 
regenerate partsof the system due to bugs* late deliveries or whatever* 
then the ability to step by SUBMITS proves to be very useful. Arbitrary 
partsof the system can be regenerated by running "<make/all()s" (i.B.*Dur 
master exec file invoked with the stepping option) and selectively 
submitting the sub-exec filesf or only those thingswhich we wish to rebuild 
while steppingover the others. 

Stepping in conjuction with the "T" option (for saving the temporary file 
created by the preprocessor) can be useful when we are going to be 
regenerating a single component of a program or system a number of times 
in succession* such as when we are fixing a bug in an element of a system 
build and we expect that several iterations will be needed to correct the 
problem. To continue our previous ex ample* suppose that we are having a 
problem with the "FileIO"unit of the "ObjIOLib"librarywhile building the 
development system* and that an exec file called "make/ObjIOLib" 
generates and installsthe library *submitting compiles and assemblies for 
all of its units* linking everything together* and finally performing the 
installation. By invoking the preprocessor with "make/ObjIOLib()st"wecan 
go into step mode and submit only those things related to the compilation 
of the "FileIO"unit* the link* and the installation of the library in the 
Intrinsic Library. Then, after each successive refinement of "FileIO"*we 
could run the saved temporary file by running "<make/ObjIOLib()r"withQut 
having to go thru the stepping process. Our alternativesto this procedure 
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are creating another exec -file to generate only the selected parts, or 
running (and rerunning) the exec -file -for the whole library^or running each 
sub-processindependently (which requiresmore ot your attention). 

Note that typing Apple-period while the preprocessor is running will abort 
the processing o-f the exec -File. 

9,4 Example Exec Files 

Example 1 — an exec file to do a Pascal compile 

This exec file does a Pascal compile and generate. Note how comments 
have been used to make the single-character Workshop commands more 
intelligible. 

$EXEC { "comp" —perform a Pascal comp II e 

XO — the name of the un i t to comp lie) 

P\ Pascal comp i 1 e}XO {source} 

{no 1 i st f i 1 e} 

{def aul t i-code file) 

G{generate code}XO 

{defaul t obj file) 
•$ENDEXEC 

Example 2 — an exec file to do an assembly 

Thisexec file performs an assembly, and allows for an optional output file 
name which may be differentfrom the source name. 

$EXEC { "assemb" — perform an assembly 

/.O -- the name of the un i t to assembl e } 
7.1 — (optional) al ternate name of OBJ output } 
f DEFAULT XI TO XO {use source name i f no output name is given } 
A {assemb 1 e }7JJ { source ) 
{no 1 i st f lie) 
%l{obj file) 
^ENDEXEC 

Example 3 — a more flexibleexec file to do Pascal compiles 

This exec file performs compiles; it allows for an output file with a 

differentname than the souce and permits the use of an alternateintrinsic 

library, 

*$EXEC { "compl" — • perform a Pascal compile 

7.0 — the name of the un i t to comp 1 1 e 

7.1 — (opt i onal ) al ternate name for OBJ file 
72 — (opt i onal ) al ternate i ntr i nsi c 1 i brar/} 

■^DEFAULT 7.1 TO 70 { i f no al ternate OBJ name use same name as source ) 
■$IF72 <> "•' THEN { use al ternate i ntr i nsi c 1 i brary ) 

PiPascal comp I ] e}?{opt i on f 1 ag) 

72{al ternate intrinsic lib) 

70 {source) 
$EL3E 

p{Pascal comp I le}70 {source) 
$END1F 
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(no ] i st + i 1 e) 
•idef aul t i -code file; 
G'Cgenerate code}%0 
:/;i{OBJ -file} 
•$ENDEXEC 

Example 4 — yet another exec -filetodo Pascal compiles 

Thiscompile exec -file will only perform the compile if eitherthe object file 
does not exist or the source fileisnewer than the object fileCi.e.^the source 
has changed since itwaslastcompiled). 

•$EXEC { "comp2" — perform a Pascal compile <onlx if really 

requ i r&d) 
%0 — the name of the un i t to comp i. 1 e 
%1 — <op ti onal ) al ternate name for OBJ file 
7.2 — <opt i onal ) a 1 ternate i ntr insi c 1 i braryO- 
^DEFAULT /;9 TO Xl { set:/.? to name of output OBJ file ) 
•^DEFAULT A? TO %0 
$IF EXISTS ("X9.obj") THEM 

$2 F NEWER <"X0.text","X9.obj") THEN Crecomp if source neiMer 

than object) 
•$SUBhIT compl <X0 ,X1 ,%2) 
$ENDIF 
•$ELSE { OBJ file does not ex i st , so generate i t ) 

$SUBMITcompi<%0,Xi,%2) 
$ENDIF 
$ENDEXEC 

It is left as an exercise as to how to change the above example to take into 
account the fact thata unit may have an arbitrary number of include filesin 
addition to its main source file jand thatthe unit will have tobe recompiled 
ifoneormore of these change. 

Example 5 — exec file "chaining" 

This example ("make/Prog") uses the "smiart" compile exec file ("comp2") 
defined in the last example to demonstrate how to "chain" exec file 
execution. Assume we want to generate a particular program made up of 
three units (unit i,.unit3)and that we have written"link/Frog'Sa smart exec 
file which performs a link only when one of the object filesfor one of the 
units is newer than the linked program file. Our generation exec file will 
use these smart exec f ilesto perform the minimal required amount of v^-orkt 
thus it may be used to determine whether we have the latestversionof the 
program without fear of wasting time. 
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$EXEC { "make./ProQ" — smart version, onl y recomp i 1 es .Si 1 i nks when 

j t has to) 
$SUBMIT comp2(uni tl) 
•^SUBMIT comp2<uriit2) 
^SUBMIT comp2(uni t3) 

R<1 i nk/Prog i run 1 i nk exec tile atter comp i 1 es have 

run so that it will get the correct 
i\ 1 e dates ) 
$ENDEXEC 

Note that in the last line of the above exec tile we have scheduled an exec 
tile to be run at a later time t as opposed to SUBMITting it now^ so that the 
tile dates tor the link step will be accessed atter the compiles have had a 
chance to run. The differences between running and submitting and exec 
files are demonstrated in the following scenario. When an exec file is 
submitted it is processed immediately by the preprocessor^with itsoutput 
going to the temporary file» which is then passed back to the V^^orkShop 
shell. The then shell runs the commands in the temporary file until it 
comes to the command to run another exec file» at which point it discards 
the remainder of the temporary file and runsthe preprocessorwith the new 
exec command. This exec file invocation in turn results in another 
temporary file of commands which is then run by the shell. 

Example 6 — arecursiveexec file to do Pascal compiles 

Thiscompile exec file will perform up to 10 compiles. Ittakes an argument 
listwith the names of the units to be compiled . 

$EXEC { "rcomp" — perform any number (up to 10) Pascal comp iles. 

1 1 cal 1 s "comp" on i ts f i rst argument and then cal 1 s i tsel f 
recurs i Mel y wi th i ts arguments sh i f ted 1 eft ) 
$IF:/.0 O •'•' THEN 
•^SUBMIT comp<'<0) { "comp" the first one } 

$3UBMITrcomp("a,X2,X3,y.4,%5,X6,/'.7,"<8,'<9) { "rcomp" the rest, less 

first } 
$END1F 
$ENDEXEC 

Example 7 — aBasicexample 

This exec file demonstrates some of the constructs in the preprocessor's 
meta-languaget by generating the BASIC interpreter. The comments in the 
body of the example should be sufficient to describe what is taking place. 
The essentialidea is that Basic is made out of three componentSf and that 
we may want to generate only one or more of them at a time. 

•$EXEC { "make/basic" —generate the BASIC i nterpreter . 

There are three parameters -- if a parameter is a "Y" (yes) 
the correspond i ng part of the system shoul d be generated: 

(0) the b-code i nterpreter 

(1) the run-time system 

(2) the command interpreter 
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It no par ame t e r s ar e sp e c i -f i e d , the e x e c f i 1 e w i 1 1 p r omp t to see 
what parts of the system should be generated. } 
$lAiRITELM •Starting generation o-f the BASIC s/sterrr" 
•$IF /-O = •'••• mD'Al = '•' AND%2= -•' THEN Cno params suppl ied — prompt 
tor i nto) 
•$WRITE -'do you want to assemble the b-code interpreter? (y or 
Cn])' 

$readch:/:o 

$WRITELN { th i s wr i tel n puts us on a new 1 i ne tor the next prompt } 

$WRITE -'do you want to comp lie the run- 1 i me system? (y or En] ) •' 

•$READCH%1 

$WRITELM 
$WRITE -'do you want to compile the command interpreter? (y or 
En])-' 

$READCH '<2 

fWRITELN 
•^ENDIF 
$ 
$IF UPPERCASE<XO) = -'y THEN {assemble the b-code interpreter } 

$SUBMIT assemb ( i nt .mai n) 
$£ND IF 
$ 
$IF UPPERCASECXl) = -'Y-" THEN { compile the run-time unit ) 

•^SUBMIT comp(b.rtuni t) 
•$ENDIF 

•$IF UPPERCASE(X2) = -Y-' OR UPPERCASE</:i ) = •'Y"' THEN 
${ compile the command interpreter ) 
%i comp i 1 e al so i t the run-t ime unit has changed ) 
•$SL1BHIT comp(b.basic) 

•$ENDIF 

•${ 1 ink i t al 1 together } 
LCI i nk}-p{note that "-p" gets around a 1 inker bug} 
b. basic 
b.rtun i t 
int. main 
hw i n 1 1 
i ostpl i b 
i ospasl \b 



basicCexecutable output) 
$ENDEXEC 

Example 8 — an exec tiletunction 

This exec tile is a function which will prompt the user tor the location at a 
Profile ^returning a string with the name of the device to which the Profile 
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is attached. Note that the -function calls itself recursively until a valid 
device name isspecitied. 

•$EXEC { "GetPro-fLoc" — get 1 ocat i on of prof i 1 e by ask inq user } 
^REQUEST 7,9 WITH 

•'Where is the profile attached ? 
(paraport/sl ot2charil/sl ot2chan2) ' 
•$SET %9 TO UPPERCASE <%9) 

•$IF <"<9 <> -TARAPORT-') AND (%9 <> ^SLuT2CHANi •' ) AND C\9 <> 
••SL0T2CHAN2-') THEN 
$WRITELN -'That is not aval iddeuice name. Let-'-"s trvaqain."" 
•^RETURN (GetProfLoc { recurs! Me cal 1 ) 
■$ELSE 

$RETURN y.9 
'$Eh\DlF 
$ENDEXEC 

9.5 Exec File Programming Tips 

The following few points may be useful to remember when creating exec 
files: 

Use modular e^ec files. It may helpfulto think of exec filesas procedures 
which are called via the SUBMIT command. The more modular your exec 
f ilesare , the easierit will be to use the stepping facility on the m . 

Create standard exec files for common functions; for ex ampler use one 
exec file to perform all your compilations. One advantage of thisisthatyou 
only have to edit one file when the interface to the tool changes (asit has in 
thecase of the assembler). 

Use optional parameters to support featuresv/hich are not always (or of ten) 
used (such as the ability to compile againstan alternateintrinsiclibrary in 
your compile exec file). The parameter mechanism is such that you can 
remain oblivious to optional parameters if you don't need the functions 
they support. 

Write your exec files to prompt for information which was not supplied in 
parameters. This way you don't need to remember the meaning of a large 
number of parameters. 

9.6 Exec File Errors 

The preprocessor can recognize a number of errors during its invocation 
and execution. The format in which most errorsare reported is: 

E RROR in < err loc> 
<curr line^- 
^errmarKerl'- 
'iierrmsg)- 



where 



<err loc> iseither 'invocation line 'or 'line#<n> of file"<file>"' 
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<curr line> is the current exec line when the errorwas detected 

<errmarker> is a line with a question mark indicating where the 
preprocessor was in <curr line> when the errorwas 
detected 

<errmsg> isone o-f the messageslistedbeiow. 

10 errors are followed by an additional line with the text of the OS error 
raisedduringthe lOoperation. The errorsdetected are as follows: 

10 Errors? 

Unabi e to open i nput file " <f i le>" . 
Unable to open temporary f i 1 e "<file>". 
Unable to access file "<f ile>" . 
Unable to rerun file "<f ile>". 

Other Errors: 

File does not begin with "$EXEC" . 
End of Exec file before "$ENDEXEC" . 
$EXEC command other thanatstart. 
Mo Exec f i 1 e spec i f i ed. 
More than 10 parameters. 
Mo closing ")" found. 
Line buffer overflow 0255 chars) . 
Inval i d Exec opt ion ; <opt i on char) . 
InMal id Exec opt ion on SUBMIT i (opt i on char) . 
End of Exec f i 1 e in comment . 
I nval i d percent ; not ""/.n" form. 
Garbage at end of command. 
Mo argument to SUBMIT. 
ELSE,'ELSEIFor EMDIFnot in IF. 
ELSEIF after ELSE. 
File containsunfinished IF. 
Nothing following "-(tilde)". 
Out of memory. Process i ng aborted. 
Bad temp file name generated? " <f i 1 e)" . 
Mo ual ue returned from f i le cal 1 ed as f unct i on . 
RETURN wi th yal ue i n f i 1 e not cal 1 ed as f unc t i on . 
and 

Inval i d command. <token) expected, 
where <token)may be: 

Str ing yal ue 

"%n" parameter 

Term i nat i ng str ing del imi ter 

"=" or "<)"' 

"<)" 

Bool ean val ue 

Comma <1 ist del imi ter) 

H j' n 
!l ••, U 
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Ual i d command keyword 
Command 
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Cha-p-ten iO 

THE UTIL-ITIES 

10.1 Introduction ........10-2 

Utilities are Executed by the Run command -from the Workshop. This 
section explains the method -for running a utility* and the common user 
inter-face. 

10.2 ByteDiff .............10-3 

ByteDif-f compares two files* byte by byte* and shows where they are 
di-f-ferent. 

10.3 ChangeSeg .............................10-4 

ChangeSeg allows you to change the segment name of an object. 

10.4 CodeSize ...10-5 

CodeSizB gives you a summary of the contents of an object file 

10.5 Diff ...........10-6 

Diff compares two text files and shows their differences. 

10.6 OumpObj .................10-7 

DumpObj displays the contents of an object file. 

10.7 DumpPatch .......................................... ..........10-7 

DumpPatch displays and edits the contents of any file. 

10.8 FileDiv and FileJoin ............................................... 10-8 

FileDiv divides large files into smaller ones. FileJoin rejoins the resulting 
small files back into the original large file. 

10.9 Grep ...10-9 

Searches for Id's. 

10.10 GxRef ...........................10-9 

GxRef provides a global cross reference. 

10.11 PackSeg ........................................................... 10-10 

PackSeg packs object code files. 

10.12 SegMap 10-11 

SegMap produces a segment map for one or more object files. 

10.13 SxRef 10-12 

SxRef produces a cross reference. 
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nr H E u"r i l i nr i e s 

iO.i Introduction 

how to run utilities 

10.2 ByteDiff 

BYTEDIFF compares any binary -files^ but once it -finds a di-f-ference between 
the two "filesrit does not always find where the differences end. 

10.3 Chang eSeg 

CHANGESEG changes the segment name in the modules in an object file. 
The first prompt asks for the object file you want to change: 

File to change: 

Changes are made in place (the file itself is changed). You are next asked: 

Map all Names (Y/N) 

If you want to change segment names in all modules* respond Y. If you want 
to be prompted for the new segment name for each module* type N. A 
response of <cr> accepts the default name. 

10.4 CodeSize 

10.5 Diff. 

DIFF is a program for comparing ".TEXT" files, in the USA Pascal 
development environment. DIFF is strongly oriented toward use with 
Pascal or Assembler source files. 

DIFF is not sensitive to upper/lower case differences. All input is shifted to 
a uniform case before comparison is done. This is in conformance with the 
language processors* which ignore case differences. 

DIFF is not sensitive to blanks. All blanks are skipped during comparison. 
This is a potential source of undetected changes* since some blanks are 
significant (in string constants, for instance). However* DIFF is insensitive 
to "trivial" changes* such as indentation adjustments* or insertion and 
deletion of spaces around operators. 

DIFF does not accept a matching context which is "too small". The current 
threshold for accepting a match is 3 consecutive matches. The M option 
allows you to change this number. This has two effects: 

Areas of the source where almost "every other line" has been changed will 
be reported as a single change block* rather than being broken into several 
small change blocks. 

Areas of the source which are "entirely different" are not broken into 
different change blocks because of trivial similarities (such as blank lines* 
lines with only "begin" or "end", etc.) 

DIFF makes a second pass through the input files* to report the changes 
detected* and to verify that matching hash codes actually represent 
matching lines. Any spurious match found during verification is reported as 
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a "JACKPOT". The probability ot a JACKPOT is very low, since two 
dif-ferent lines must hash to the same code at a location in each -file which 
extends the longest common subsequence, and in a matching context which 
is large enough to exceed the threshold for acceptance. 

DIFF can handle -files with up to 2000 lines. 

DIFF firstprompts you -for two input file names: the "new" filerand the "old" 
file. DIFF appends ".TEXT" to these file names^ if it is not present. EjIFF 
then prompts you for a filename for the listing file. Type carriage-return to 
send the listing to the console. 

DIFF does not (currently) Know about INCLUDE files. However^ DIFF does 
allow the processing of several pairs of files to be sent to the same listing 
file. ThuSf when DIFF is finished with one pair of filest it prompts you for 
another pair of input files. To terminate DIFF, simply type carriage-return 
in response to the prompt for an input file name. 

The output produced by DIFF consists of blocks of "changed" lines. Each 
block of changes is surrounded by a few lines of "context" to aid in finding 
the lines in a hard-copy listing of the files. 

There are three kinds of change blocks: 

INSERTION — a block of lines in the "new" file which does not appear in the 
"old" file. 

DELETION — a block of lines in the "old" file which does not appear in the 
"new" file. 

REPLACEMENT — a block of lines in the "new" file which replaces a 
corresponding block of different lines in the old file. 

Large blocks of changes are printed in summary fashion: a few lines at the 
beginning of the changes and a few lines at the end of the changes, with an 
indication of how many lines were skipped. 

DIFF has three options which allow you to change the number of context 
lines displayed (+C), the number of lines required to constitute a match (+M), 
and the number of lines displayed at the beginning of a long block of 
differences (+D). To set one of these numbers, type the option name 
followed by the new number to the prompt for the first input file name. +D 
100, for example, causes DIFF to print out up to 100 lines of a block of 
differences before using an ellipsis. The maximum number of context lines 
you can get is8. 

10.6 DumpObj. 

DUMPOBJ is a disassembler for 68000 code. It can disassemble either an 
entire file, or specific modules (procedures) within the file. DUMPOBJ 
replaces DUMPMCODE, 

DUMPOBJ first asks for the input file which should be an unlinked object 
file. The output (listing) file defaults to CONSOLE:. You. are asked whether 
you want to dump 
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AQl, S(ome» or Pfariicular modules. 

If you respond S(ome> DUMPOBJ asks you for confirma-tion be-fore dumping 
each module. A response of <ESC> gets you back to the top level. If you 
respond P(articulart DUMPOBJ asks you for the particular module(5) you 
want dumped. 

The next question is: 'Dump file positions CN3?'The file position isa number 
of the form iI0>0003where the first digit is the block number (decimal) within 
the file and the second number is the byte number (hexadecimal) within the 
block at which the module starts. This information can be used in 
conjunction with the PATCH program. Finally? DUMPOBJ asks if you want 
the object code disassembled. 

10.7 DumpPatch 

DumpPatch is a combination of DumpHex and Patch. 

DumpHex provides a textual representation of the contents of any file. The 
file dump is block-oriented with the hexadecimal representation on the left 
and the corresponding ASCII representation on the right. If a byte cannot be 
converted to a printable character, a dot is substituted. 

When DumpHex is Run, it asks you for the name of the output file. A .TEXT 
extension is added if necessary. To direct the output to the console, type 
carriage return. After getting a valid output file name, DumpHex asks for 
the input file to be dumped. No extensions are appended, so give the full 
filename. Once a file has been completely dumped, DumpHex asks you for 
the next file to dump. Type carriage return to exit the program. 

After opening the input file, DumpHex asks you which block to dump. The 
default (carriage return) is block 0. If the output is going to a file, you are 
asked which block is the last you want dumped. The default here (carriage 
return) is the last block in the file. 

The format of the console output depends on the number of lines your screen 
has. If fewer than 33 lines are available, the output is displayed only a half 
block at a time. Between blocks or block halves you have the option to 

Type <5pace> to continue, <escape> to exit. 

Escape returns to the prompt for an input file. 

Patch allows you to examine and change the contents of any file. Th© 
display of the file's contents is exactly like that of DumpHex. With Patch, 
however, you can use the cursor control keys to move around in the block 
and change the value of any byte using either the hexadecimal 
representation on the left or the ASCII representation on the right. 

After Running Patch you are asked for the full name of the file to patch. 
Carriage return exits Patch. No extension is appended to the file name. You 
are then asked for the number of the block you want to mess around with. 
Carriage return here returns you to the file name prompt. 

The block is displayed with the cursor in the upper left corner at word of 
the block. The arrow keys can be used to move around in the block. If you 
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move the cursor up -from the toplinej you get the bottom line of the 
preceding block. Similarly, i-f you move down from the bottom line, you 
move into the top line of the next block. 

When the cursor is on the hexadecimal side of the display, you can change 
any byte by typing the new hexadecimal value. Any non-hex characters are 
ignored. You can impress your friends by pointing out that the change is 
reflected automatically in the ASCII portion of the display. When the 
cursor is on the ASCII side, type any character to replace the value of the 
byte. 

Until you move out of the block you can undo any changes by typing 
<escape>. 

10.8 FileDiv and FileJoin. 

It is often necessary to distribute files that are too large to fit onto a single 
floppy diskette. FILEDIV can be used to break a large file into several 
diskette-sized pieces. FILEDIV can then be used to rejoin these pieces at 
the file's destination. These two programs replace the TRANSFER program^ 

To divide a large text or object file. Run FILEDIV. 

Input file: <give the name of the file to be divided> 

Output file: <give the name to be used for the output files) 

Do not include the suffix in the file name. If, for example, you want to 
divide TEMP.TEXT, give TEMP as the input file, and TEMP (or whatever) as 
the output file. FILEDIV will create a group of files named TEMP.i.TEXT, 
TEMP.2.TEXT, and soon, until TEMP.TEXT is completely divided up. If you 
use the drive number (#9:, for example), rather than the volume name, the 
new files can be written to multiple diskettes. When space on a diskette is 
exhausted, FILEDIV asks you to insert another diskette. 

To rejoin the pieces of the file, Run FILEJOIN. Using the example given 
above, we can rejoin TEMP.i.TEXT and friends into TEMP.TEXT by 
responding: 

Input file: TEMP <will read TEMP.i.TEXT, etc> 

Output file: TEMP < will create TEMP.TEXT> 

FILEDIV and FILEJOIN use regular directories, so a spurious sex change 
cannot destroy your file. Files are verified in both directions. 

10.9 Grep 

10.10 GxRef. 

GXREF lists all the modules which call a given procedure, and all the 
modules which that procedure calls. It provides a global cross reference of 
subroutines and modules. 

10.11 Packseg 

10.12 SegMap 

SEGMAP produces a segment map of one or more object files. The first 
prompt: 
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Files to Map ? 

accepts either an object -file name or a command file name. A command 
file must be preceded with a <. SEGMAP adds the .TEXT suffix to the 
command -file name. The next prompt*. 

Listing File ? 

directs the map information to the file given. A response of #1: or 
CONSOLE:^ for example^ send the map information to the screen. The map 
information includes the object -file name, the name of the unit in the file* 
the names of the segments used in that unit (if any)^ and the new segment 
names. 

10.13 SxRef 
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Apple publications -would like to leaxn about readers and Av^hat you think about 
this manual in order to make better manuals in the future. Please fill out this 
form, or^yrritealloverit, and send it to us. We promise to read it. 

Is it quick and easy to find the information you need in this manual? 
[ ] ali^rays [ ] often [ ] sometimes [ ] seldom [ ] never 

Comments . 

What made this manual easy to use? 



What made this manual hard to use?. 



Ho^w are you using this manual? 

[ ] learning to use the product [ ] reference [ ] both reference and learning 

[ ] other ^ _--__„ 

Please comment on, for example, accuracy, level of detail, number and 
usefulness of examples, length or brevity of explanation, style, use of 
graphics, usefulness of the index, organization, suitability to your particular 
needs, readability. 



What do you like most about the manual?. 



What do you like least about the manual?. 



In school have you completed? 

[ ] high school [ ] some college [ ] BA/BS [ ] MA/MS [ ] more 

Comments 

What is 3^ur job title? 

HoAv long have you been programming? 

[ ] 0-1 years [ ] 1-3 [ ] 4-7 [ ] over 7 [ ] not a programmer 

Comments 



What languages do you use on yotir Lisa? (check each) 
[ ] Pascal [ ] BASIC [ ] COBOL [ ] other 

Comments « 



What magazines do you read?. 



